List Posts

`GET /posts`

Returns the social posts made from your clips on YouTube, Instagram and TikTok: what is scheduled, what is still uploading, what is live (with its public URL and publish time), and what failed (with a plain-language reason). Posts scheduled by hand from the shorts list and posts made by channel automation are both included; the source field tells them apart.

Typical use: after shorts.completed you schedule clips to your accounts; poll this endpoint once a minute with date=published&since=<last check> to collect the links of posts that just went live.

Query parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (starting from 1)
`limit`	number	`50`	Items per page (1–100)
`status`	string	—	`scheduled`, `processing`, `published`, `failed` or `canceled` (see Post statuses)
`platform`	string	—	`youtube`, `instagram` or `tiktok`
`source`	string	—	`manual` (scheduled from the shorts list) or `automation` (channel automation)
`requestId`	string	—	Only posts made from this request
`shortId`	string	—	Only posts made from this clip
`since`	string	—	ISO 8601 lower bound
`until`	string	—	ISO 8601 upper bound
`date`	string	`scheduled`	Which timestamp `since`/`until` filter and sort by: `scheduled` (the planned time) or `published` (when it went live; implies `status=published`)

Results are newest first.

Request

# posts that went live in the last hour
curl -H "X-API-Key: sk_ssemble_your_key" \
  "https://aiclipping.ssemble.com/api/v1/posts?date=published&since=2026-10-09T05:00:00Z&limit=100"

Response

{
  "data": {
    "posts": [
      {
        "id": "6ac8829c0000000000000001",
        "platform": "youtube",
        "status": "published",
        "scheduledAt": "2026-10-09T06:15:00.000Z",
        "publishedAt": "2026-10-09T06:15:02.827Z",
        "url": "https://www.youtube.com/watch?v=cR9Ki-TtW-w",
        "shortId": "a1581dd6-9f1c-4a7e-9b1a-2c3d4e5f6a7b",
        "requestId": "6a8d8d41aefabd4ce4f5b66f",
        "title": "Build a VM for VS Code",
        "account": { "handle": "deepak anand" },
        "source": "manual",
        "error": null,
        "errorCode": null,
        "retryable": null,
        "createdAt": "2026-10-09T05:50:12.000Z"
      },
      {
        "id": "6ac8829e0000000000000002",
        "platform": "tiktok",
        "status": "processing",
        "scheduledAt": "2026-10-09T06:15:00.000Z",
        "publishedAt": null,
        "url": null,
        "shortId": "a1581dd6-9f1c-4a7e-9b1a-2c3d4e5f6a7b",
        "requestId": "6a8d8d41aefabd4ce4f5b66f",
        "title": "Build a VM for VS Code",
        "account": { "handle": "DripSnipsHQ" },
        "source": "manual",
        "error": null,
        "errorCode": null,
        "retryable": null,
        "createdAt": "2026-10-09T05:50:12.000Z"
      },
      {
        "id": "6ac8829e0000000000000003",
        "platform": "instagram",
        "status": "failed",
        "scheduledAt": "2026-10-09T06:15:00.000Z",
        "publishedAt": null,
        "url": null,
        "shortId": "a1581dd6-9f1c-4a7e-9b1a-2c3d4e5f6a7b",
        "requestId": "6a8d8d41aefabd4ce4f5b66f",
        "title": "Build a VM for VS Code",
        "account": { "handle": "dripsnips" },
        "source": "automation",
        "error": "Instagram disconnected this account. Reconnect it in Social Accounts, then schedule the post again.",
        "errorCode": "auth_expired",
        "retryable": false,
        "createdAt": "2026-10-09T05:50:12.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "totalPages": 1,
      "totalCount": 3
    }
  }
}

Field	Description
`id`	Post ID
`platform`	`youtube`, `instagram` or `tiktok`
`status`	See Post statuses
`scheduledAt`	When the post was due to go out
`publishedAt`	When the platform confirmed it (only for `published`)
`url`	Public URL of the post (only for `published`)
`shortId`, `requestId`	The clip and the request it came from
`title`	Caption / title used for the post
`account.handle`	The connected account it was posted to
`source`	`manual` or `automation`
`error`, `errorCode`, `retryable`	Only for `failed`: a plain-language reason, a stable code, and whether rescheduling can fix it (see below)

The same posts array is also attached to each short in GET /shorts/:id.

Post statuses

Status	Meaning
`scheduled`	Queued for a future time
`processing`	Being uploaded, or accepted by the platform and waiting for it to finish (TikTok typically takes 1–3 minutes to assign the public URL)
`published`	Live; `url` and `publishedAt` are set
`failed`	Not published; `error` says why
`canceled`	Removed by the user before it went out

Typical time from scheduledAt to published: YouTube within seconds, Instagram 1–3 minutes, TikTok 2–4 minutes.

Failure reasons

`errorCode`	Meaning	`retryable`
`auth_expired`	The connected account's token expired or was revoked. Reconnect it in Social Accounts.	`false`
`daily_cap`	The platform's daily posting or upload limit was reached. Resets within 24 hours.	`true`
`account_restricted`	TikTok's spam filter blocked the post from this account (`spam_risk`). The user has to resolve it in the TikTok app.	`false`
`account_not_eligible`	Account type can't post this way (Instagram personal account, Google account without a YouTube channel, TikTok permissions not granted).	`false`
`media_rejected`	The platform rejected the video (length, format, resolution, frame rate). Re-export the clip.	`false`
`video_missing`	The clip's video file is no longer available. Re-create the clip.	`false`
`processing_timeout`	The platform didn't finish processing the video in time.	`true`
`rate_limited`	The platform is temporarily limiting requests.	`true`
`unknown`	Anything else; `error` includes the platform's own message.	`true`

retryable: true means scheduling the post again at a later time is a reasonable fix; false means the user has to change something first.

Polling for newly published posts

Keep the time of your last check and ask for everything published since then. publishedAt is the watermark and id is the dedupe key.

let since = new Date().toISOString();
const seen = new Set();
 
setInterval(async () => {
  const res = await fetch(
    `https://aiclipping.ssemble.com/api/v1/posts?date=published&since=${encodeURIComponent(since)}&limit=100`,
    { headers: { 'X-API-Key': 'sk_ssemble_your_key' } }
  );
  const { data } = await res.json();
  for (const post of data.posts) {
    if (seen.has(post.id)) continue;
    seen.add(post.id);
    await submitLink(post.platform, post.url, post.publishedAt); // your side
    if (post.publishedAt > since) since = post.publishedAt;
  }
}, 60_000);

Once a minute is well within the rate limit (500 requests per minute per key).

Errors

HTTP	`error.code`	When
400	`invalid_request`	A query parameter is invalid; the message names it
401	`missing_api_key` / `invalid_api_key`	Missing, malformed or revoked key
403	`subscription_required`	The key's account has no active subscription
429	`rate_limit_exceeded`	Too many requests; see `X-RateLimit-*` headers and `details.retryAfter`

On this page