List Scheduled Posts

curl -X GET "https://api.hooked.so/v1/schedule/list?status=pending&platform=youtube&limit=20" \
  -H "x-api-key: your_api_key_here"

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']}")

{
  "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
  }
}

{
  "success": true,
  "message": "Scheduled posts fetched successfully",
  "data": {
    "scheduledPosts": [],
    "total": 0,
    "limit": 50,
    "offset": 0
  }
}

GET

schedule

list

curl -X GET "https://api.hooked.so/v1/schedule/list?status=pending&platform=youtube&limit=20" \
  -H "x-api-key: your_api_key_here"

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']}")

{
  "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
  }
}

{
  "success": true,
  "message": "Scheduled posts fetched successfully",
  "data": {
    "scheduledPosts": [],
    "total": 0,
    "limit": 50,
    "offset": 0
  }
}

Try it out! Use the API playground on the right to test the List Scheduled Posts endpoint directly.

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

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

Endpoint

GET /v1/schedule/list

Headers

string

required

Your API key from API Settings

Query Parameters

string

Filter by post status:

pending - Waiting to be published
published - Successfully published
failed - Publication failed
draft - Draft posts (not scheduled)

string

Filter by platform:

youtube - YouTube posts
tiktok - TikTok posts
instagram - Instagram posts

number

default:"50"

Number of results to return (max: 100)

number

default:"0"

Offset for pagination

Response

boolean

Whether the request was successful

object

Show Data Object

array

Array of scheduled posts

Show Scheduled Post Object

string

Unique schedule ID

string

Current status: pending, published, failed, or draft

string

ISO 8601 datetime when the post will be published

string

Target platform: youtube, tiktok, or instagram

object

Connected platform account

Show Integration Object

string

Integration ID

string

Platform type

object

Account details (name, username, avatarUrl)

object

Video information

Show Video Object

string

Video ID

string

Video name

string

Signed URL to the video file

string

Signed URL to the thumbnail

number

Video duration in seconds

object

Platform-specific metadata (title, description, tags, etc.)

string

When the schedule was created

string

When the schedule was last updated

number

Total number of matching posts

number

Applied limit

number

Applied offset

Request Examples

Basic Request

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

// 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

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;
}

curl -X GET "https://api.hooked.so/v1/schedule/list?status=pending&platform=youtube&limit=20" \
  -H "x-api-key: your_api_key_here"

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']}")

Response Examples

{
  "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
  }
}

{
  "success": true,
  "message": "Scheduled posts fetched successfully",
  "data": {
    "scheduledPosts": [],
    "total": 0,
    "limit": 50,
    "offset": 0
  }
}

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

Use Webhooks

Instead of polling, use webhooks to get notified when posts are published or fail.

Paginate Large Results

For accounts with many scheduled posts, use offset/limit pagination.

Filter by Status

Filter by pending to see upcoming posts, or failed to find issues.

Check Times

All times are in UTC. Convert to local time for display.

Next Steps

Schedule Video

Schedule a new video for publishing

Update Schedule

Change scheduled time or metadata

Cancel Schedule

Cancel a scheduled post

View Details

Get full details of a scheduled post

Authorizations

x-api-key

string

header

required

Query Parameters

status

enum<string>

Filter by status

Available options:

pending,

published,

failed,

draft

platform

enum<string>

Filter by platform

Available options:

youtube,

tiktok,

instagram

limit

integer

default:50

Number of results (max 100)

offset

integer

default:0

Pagination offset

Response

200

Success

Getting Started

Resources

Videos

Templates

Trends

Niches

Social Accounts

Social Search

Scheduling

Overview

Endpoint

Headers

Query Parameters

Response

Request Examples

Basic Request

With Filters

Response Examples

Status Values

Best Practices

Use Webhooks

Paginate Large Results

Filter by Status

Check Times

Next Steps

Schedule Video

Update Schedule

Cancel Schedule

View Details

Authorizations

Query Parameters

Response

​Overview

​Endpoint

​Headers

​Query Parameters

​Response

​Request Examples

​Basic Request

​With Filters

​With Pagination

​Response Examples

​Status Values

​Best Practices

Use Webhooks

Paginate Large Results

Filter by Status

Check Times

​Next Steps

Schedule Video

Update Schedule

Cancel Schedule

View Details

Authorizations

Query Parameters

Response

Overview

Endpoint

Headers

Query Parameters

Response

Request Examples

Basic Request

With Filters

With Pagination

Response Examples

Status Values

Best Practices

Next Steps