> ## 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
> List your team's scheduled posts, newest first
## Overview
Lists the posts your team has scheduled, most recently created first, with the video and account each one publishes to. Posts published directly from the dashboard (not scheduled) are not included.
```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"
```
```javascript Node.js theme={null}
const params = new URLSearchParams({ status: 'pending', limit: '20' });
const response = await fetch(`https://api.hooked.so/v1/schedule/list?${params}`, {
headers: { 'x-api-key': process.env.HOOKED_API_KEY }
});
const { data } = await response.json();
console.log(`${data.total} pending posts`);
```
```python Python theme={null}
import requests
response = requests.get(
'https://api.hooked.so/v1/schedule/list',
params={'status': 'failed', 'limit': 50, 'offset': 0},
headers={'x-api-key': 'your_api_key_here'}
)
for post in response.json()['data']['scheduledPosts']:
print(post['id'], post['platform'], post['scheduledDateTime'])
```
```json Success theme={null}
{
"success": true,
"message": "Scheduled posts fetched successfully",
"data": {
"scheduledPosts": [
{
"id": "cm6f7g8h9i0j1k2l3m4n5o6p7",
"status": "pending",
"scheduledDateTime": "2026-10-05T15:00:00.000Z",
"platform": "youtube",
"integration": {
"id": "cm3c4d5e6f7g8h9i0j1k2l3m4",
"type": "youtube",
"account": {
"id": "UC1234567890",
"name": "My YouTube Channel",
"username": "mychannel",
"avatarUrl": "https://yt3.ggpht.com/..."
}
},
"video": {
"id": "cm5e6f7g8h9i0j1k2l3m4n5o6",
"name": "5 tips for better sleep",
"url": "https://.../video.mp4",
"thumbnail": "https://.../thumbnail.jpg",
"durationInSeconds": 42
},
"platformData": {
"title": "5 tips for better sleep",
"privacyStatus": "public"
},
"createdAt": "2026-10-01T10:30:00.000Z",
"updatedAt": "2026-10-01T10:30:00.000Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
}
```
```json 400 Bad platform theme={null}
{
"code": "bad_request",
"message": "platform: Must be one of tiktok, youtube, instagram, facebook",
"errorCode": "INVALID_INPUT",
"details": {}
}
```
## Errors
| Status | When |
| - | - |
| 400 | `platform` is not one of the four values |
| 401 | Missing or invalid API key (`code: "not_authenticated"`) |
| 403 | The team does not have the Hooked app product (`code: "entitlement_required"`) |
| 500 | `{ "success": false, "message": "Failed to fetch scheduled posts", "error": "..." }` |
## Next Steps
One post in detail
Schedule another video
## 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: []
tags:
- name: Videos
description: Create projects, follow them and render videos
- name: Account Analysis
description: Analyze TikTok and YouTube accounts
- name: Channels
description: Connected social accounts you publish to
- name: Publish
description: Schedule videos to your connected accounts
- name: Images
description: 'Image editing: background removal and expansion'
- name: Media
description: 'Your media library: list, import from a URL, upload a file'
- name: Avatars
description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
/v1/schedule/list:
get:
tags:
- Publish
summary: List Scheduled Posts
description: >-
Your team's scheduled posts, most recently created first, with the video
and account each one publishes to. Posts published directly from the
dashboard are not included.
operationId: listScheduledPosts
parameters:
- name: status
in: query
required: false
description: >-
Keep only posts with this status. Matched exactly; any other value
returns an empty list.
schema:
type: string
enum:
- pending
- published
- failed
- name: platform
in: query
required: false
description: Keep only posts to this platform. Any other value answers 400.
schema:
type: string
enum:
- tiktok
- youtube
- instagram
- facebook
- name: limit
in: query
required: false
description: Page size (1-100). Invalid values fall back to the default.
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: offset
in: query
required: false
description: Rows to skip. Invalid values fall back to 0.
schema:
type: integer
minimum: 0
default: 0
responses:
'200':
description: Scheduled posts
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
scheduledPosts:
type: array
items:
$ref: '#/components/schemas/ScheduledPost'
description: One page of posts
total:
type: integer
description: >-
Posts that match the filters (all pages). You are done
when `offset + limit >= total`.
limit:
type: integer
description: Page size used
offset:
type: integer
description: Offset used
'400':
description: '`platform` is not one of the four values'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: bad_request
message: 'platform: Must be one of tiktok, youtube, instagram, facebook'
errorCode: INVALID_INPUT
details: {}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/EntitlementRequired'
'429':
$ref: '#/components/responses/RateLimited429'
'500':
$ref: '#/components/responses/InternalError'
security:
- ApiKeyAuth: []
components:
schemas:
ScheduledPost:
type: object
properties:
id:
type: string
description: Scheduled post id
status:
type: string
enum:
- pending
- published
- failed
example: pending
description: >-
`pending` while waiting for its time (or being published),
`published` once the platform accepted it, `failed` when publishing
failed
scheduledDateTime:
type: string
format: date-time
description: When it is (or was) published
platform:
type: string
enum:
- tiktok
- youtube
- instagram
- facebook
description: The integration's platform
integration:
type: object
properties:
id:
type: string
description: Integration id
type:
type: string
enum:
- tiktok
- youtube
- instagram
- facebook
description: Platform
account:
type: object
description: Any field can be `null`
properties:
id:
type: string
nullable: true
description: Account id on the platform
name:
type: string
nullable: true
description: Display name
username:
type: string
nullable: true
description: Handle
avatarUrl:
type: string
nullable: true
description: Profile picture URL
video:
type: object
properties:
id:
type: string
description: The video being published
name:
type: string
nullable: true
description: Video name
url:
type: string
description: Signed URL of the video, or `""` if unavailable
thumbnail:
type: string
description: Signed URL of the thumbnail, or `""`
durationInSeconds:
type: number
description: Video duration
platformData:
type: object
additionalProperties: true
description: >-
The post details you sent while the post is not published. Once
published it is replaced by what the platform returned: `videoId`
and `videoUrl` (YouTube), `videoId` and `instagramId` (Instagram),
`videoId`, `publish_id` and `upload_url` (TikTok).
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ApiError:
type: object
description: >-
Error shape used by the scheduling, integration and social account
endpoints.
properties:
code:
type: string
enum:
- bad_request
- forbidden
- not_found
message:
type: string
errorCode:
type: string
enum:
- INVALID_INPUT
- FORBIDDEN
- RESOURCE_NOT_FOUND
details:
type: object
additionalProperties: true
required:
- code
- message
example:
code: not_found
message: Schedule not found
errorCode: RESOURCE_NOT_FOUND
details:
resource_id: clx...
resource_type: Schedule
Error401:
type: object
description: Missing or invalid `x-api-key`.
properties:
code:
type: string
enum:
- not_authenticated
message:
type: string
example: Not authenticated
errorCode:
type: string
enum:
- NOT_AUTHENTICATED
details:
type: object
additionalProperties:
type: string
example:
code: not_authenticated
message: Not authenticated
errorCode: NOT_AUTHENTICATED
details:
x-api-key: Header not provided or API Key invalid
EntitlementRequired403:
type: object
description: >-
Valid key, but the team does not have the product this endpoint belongs
to.
properties:
code:
type: string
enum:
- entitlement_required
error:
type: string
enum:
- entitlement_required
message:
type: string
product:
type: string
example: app
required:
- code
- error
- message
- product
example:
code: entitlement_required
error: entitlement_required
message: This endpoint requires the "app" product.
product: app
Error500:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
error:
type: string
description: Present on some endpoints
example:
success: false
message: Internal server error
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
EntitlementRequired:
description: The team does not have the product this endpoint needs
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequired403'
RateLimited429:
description: >-
Your team is over a rate limit: 30 POST requests per minute, 120 other
requests per minute, or 3 downloads of your URLs running at once.
Nothing ran and nothing was charged: wait `Retry-After` seconds and send
the request again. See [Rate
limits](/guides/error-handling#rate-limits-429).
headers:
Retry-After:
description: Seconds to wait before sending again.
schema:
type: integer
X-RateLimit-Limit:
description: The limit of the bucket you hit (not sent for the download cap).
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in this window: 0 (not sent for the download cap).'
schema:
type: integer
X-RateLimit-Reset:
description: >-
When the window ends, in Unix seconds (not sent for the download
cap).
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- RATE_LIMITED
message:
type: string
retryAfterSeconds:
type: integer
required:
- success
- errorCode
- message
- retryAfterSeconds
example:
success: false
errorCode: RATE_LIMITED
message: >-
Rate limit exceeded: 30 POST requests per minute per team. Retry
after 12 s.
retryAfterSeconds: 12
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.