Skip to main content
GET
/
v1
/
schedule
/
list
curl -X GET "https://api.hooked.ai/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.tryhooked.ai/...",
          "thumbnail": "https://cdn.tryhooked.ai/...",
          "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

Request Examples

Basic Request

const response = await fetch('https://api.hooked.ai/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.ai/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.ai/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.ai/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.tryhooked.ai/...",
          "thumbnail": "https://cdn.tryhooked.ai/...",
          "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

StatusDescription
pendingScheduled and waiting to be published at the specified time
publishedSuccessfully published to the platform
failedPublishing failed (check platformData for error details)
draftSaved 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

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