List Scheduled Posts - Hooked API Documentation

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

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

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"

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

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

x-api-key

string

required

Your API key from API Settings

Query Parameters

status

string

Filter by post status:

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

platform

string

Filter by platform:

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

limit

number

default:"50"

Number of results to return (max: 100)

offset

number

default:"0"

Offset for pagination

Response

success

boolean

Whether the request was successful

data

object

Show Data Object

scheduledPosts

array

Array of scheduled posts

Show Scheduled Post Object

string

Unique schedule ID

status

string

Current status: pending, published, failed, or draft

scheduledDateTime

string

ISO 8601 datetime when the post will be published

platform

string

Target platform: youtube, tiktok, or instagram

integration

object

Connected platform account

Show Integration Object

string

Integration ID

type

string

Platform type

account

object

Account details (name, username, avatarUrl)

video

object

Video information

Show Video Object

string

Video ID

name

string

Video name

url

string

Signed URL to the video file

thumbnail

string

Signed URL to the thumbnail

durationInSeconds

number

Video duration in seconds

platformData

object

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

createdAt

string

When the schedule was created

updatedAt

string

When the schedule was last updated

total

number

Total number of matching posts

limit

number

Applied limit

offset

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"

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

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

Delete Search Schedule Video

​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