> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Scheduled Posts

> Get all scheduled posts for your account with filtering options

<Note>
  **Try it out!** Use the API playground on the right to test the List Scheduled Posts endpoint directly.
</Note>

## Overview

List all videos scheduled for publishing to your connected social platforms. Use filters to find specific posts by status or platform.

This endpoint is useful for:

* Building a content calendar view
* Monitoring scheduled content status
* Managing your publishing pipeline

<Info>
  Scheduled posts are automatically published at their scheduled time. The status will change from `pending` to `published` or `failed` after the publishing attempt.
</Info>

***

## Endpoint

```
GET /v1/schedule/list
```

***

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key from [API Settings](https://hooked.so/settings/api)
</ParamField>

***

## Query Parameters

<ParamField query="status" type="string">
  Filter by post status:

  * `pending` - Waiting to be published
  * `published` - Successfully published
  * `failed` - Publication failed
  * `draft` - Draft posts (not scheduled)
</ParamField>

<ParamField query="platform" type="string">
  Filter by platform:

  * `youtube` - YouTube posts
  * `tiktok` - TikTok posts
  * `instagram` - Instagram posts
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of results to return (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Offset for pagination
</ParamField>

***

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Data Object">
    <ResponseField name="scheduledPosts" type="array">
      Array of scheduled posts

      <Expandable title="Scheduled Post Object">
        <ResponseField name="id" type="string">
          Unique schedule ID
        </ResponseField>

        <ResponseField name="status" type="string">
          Current status: `pending`, `published`, `failed`, or `draft`
        </ResponseField>

        <ResponseField name="scheduledDateTime" type="string">
          ISO 8601 datetime when the post will be published
        </ResponseField>

        <ResponseField name="platform" type="string">
          Target platform: `youtube`, `tiktok`, or `instagram`
        </ResponseField>

        <ResponseField name="integration" type="object">
          Connected platform account

          <Expandable title="Integration Object">
            <ResponseField name="id" type="string">
              Integration ID
            </ResponseField>

            <ResponseField name="type" type="string">
              Platform type
            </ResponseField>

            <ResponseField name="account" type="object">
              Account details (name, username, avatarUrl)
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="video" type="object">
          Video information

          <Expandable title="Video Object">
            <ResponseField name="id" type="string">
              Video ID
            </ResponseField>

            <ResponseField name="name" type="string">
              Video name
            </ResponseField>

            <ResponseField name="url" type="string">
              Signed URL to the video file
            </ResponseField>

            <ResponseField name="thumbnail" type="string">
              Signed URL to the thumbnail
            </ResponseField>

            <ResponseField name="durationInSeconds" type="number">
              Video duration in seconds
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="platformData" type="object">
          Platform-specific metadata (title, description, tags, etc.)
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          When the schedule was created
        </ResponseField>

        <ResponseField name="updatedAt" type="string">
          When the schedule was last updated
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of matching posts
    </ResponseField>

    <ResponseField name="limit" type="number">
      Applied limit
    </ResponseField>

    <ResponseField name="offset" type="number">
      Applied offset
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Request Examples

### Basic Request

```javascript theme={null}
const response = await fetch('https://api.hooked.so/v1/schedule/list', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY
  }
});

const data = await response.json();
console.log('Scheduled posts:', data.data.scheduledPosts);
```

### With Filters

```javascript theme={null}
// Get only pending TikTok posts
const url = new URL('https://api.hooked.so/v1/schedule/list');
url.searchParams.set('status', 'pending');
url.searchParams.set('platform', 'tiktok');
url.searchParams.set('limit', '20');

const response = await fetch(url, {
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY
  }
});

const data = await response.json();
```

### With Pagination

```javascript theme={null}
async function getAllScheduledPosts() {
  const allPosts = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api.hooked.so/v1/schedule/list?limit=${limit}&offset=${offset}`,
      { headers: { 'x-api-key': process.env.HOOKED_API_KEY } }
    );

    const { data } = await response.json();
    allPosts.push(...data.scheduledPosts);

    if (data.scheduledPosts.length < limit) break;
    offset += limit;
  }

  return allPosts;
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.hooked.so/v1/schedule/list?status=pending&platform=youtube&limit=20" \
    -H "x-api-key: your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.hooked.so/v1/schedule/list',
      headers={'x-api-key': 'your_api_key_here'},
      params={
          'status': 'pending',
          'platform': 'youtube',
          'limit': 20
      }
  )

  data = response.json()
  for post in data['data']['scheduledPosts']:
      print(f"{post['video']['name']} - {post['scheduledDateTime']}")
  ```
</RequestExample>

***

## Response Examples

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "message": "Scheduled posts fetched successfully",
    "data": {
      "scheduledPosts": [
        {
          "id": "post_abc123",
          "status": "pending",
          "scheduledDateTime": "2024-03-15T14:00:00.000Z",
          "platform": "youtube",
          "integration": {
            "id": "int_yt_xyz789",
            "type": "youtube",
            "account": {
              "id": "UC1234567890",
              "name": "My YouTube Channel",
              "username": "mychannel",
              "avatarUrl": "https://yt3.ggpht.com/..."
            }
          },
          "video": {
            "id": "vid_def456",
            "name": "10 Tips for Productivity",
            "url": "https://cdn.hooked.so/...",
            "thumbnail": "https://cdn.hooked.so/...",
            "durationInSeconds": 45
          },
          "platformData": {
            "title": "10 Tips for Productivity",
            "description": "Learn how to boost your productivity...",
            "tags": ["productivity", "tips", "workflow"],
            "privacyStatus": "public"
          },
          "createdAt": "2024-03-10T10:00:00.000Z",
          "updatedAt": "2024-03-10T10:00:00.000Z"
        }
      ],
      "total": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```

  ```json Empty Response theme={null}
  {
    "success": true,
    "message": "Scheduled posts fetched successfully",
    "data": {
      "scheduledPosts": [],
      "total": 0,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</ResponseExample>

***

## Status Values

| Status      | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `pending`   | Scheduled and waiting to be published at the specified time |
| `published` | Successfully published to the platform                      |
| `failed`    | Publishing failed (check platformData for error details)    |
| `draft`     | Saved but not scheduled for publishing                      |

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Webhooks" icon="webhook">
    Instead of polling, use webhooks to get notified when posts are published or fail.
  </Card>

  <Card title="Paginate Large Results" icon="list">
    For accounts with many scheduled posts, use offset/limit pagination.
  </Card>

  <Card title="Filter by Status" icon="filter">
    Filter by `pending` to see upcoming posts, or `failed` to find issues.
  </Card>

  <Card title="Check Times" icon="clock">
    All times are in UTC. Convert to local time for display.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Schedule Video" icon="calendar-plus" href="/api-reference/schedule/create">
    Schedule a new video for publishing
  </Card>

  <Card title="Update Schedule" icon="edit" href="/api-reference/schedule/update">
    Change scheduled time or metadata
  </Card>

  <Card title="Cancel Schedule" icon="trash" href="/api-reference/schedule/delete">
    Cancel a scheduled post
  </Card>

  <Card title="View Details" icon="eye" href="/api-reference/schedule/details">
    Get full details of a scheduled post
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v1/schedule/list
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/schedule/list:
    get:
      tags:
        - Scheduling
      summary: List Scheduled Posts
      description: Get all scheduled posts for your account with filtering options
      operationId: listScheduledPosts
      parameters:
        - name: status
          in: query
          description: Filter by status
          required: false
          schema:
            type: string
            enum:
              - pending
              - published
              - failed
              - draft
        - name: platform
          in: query
          description: Filter by platform
          required: false
          schema:
            type: string
            enum:
              - youtube
              - tiktok
              - instagram
        - name: limit
          in: query
          description: Number of results (max 100)
          required: false
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          description: Pagination offset
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Success
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````