Posts

List posts in a workspace, or fetch a single post and its per-platform targets.

List posts

GET/v1/posts

Query parameters

Param	Type	Description
limit	integer	Max results per page. Default 20, max 100.
cursor	string	Opaque pagination cursor from the previous response's `next_cursor`.
status	string	Filter by post status: `pending`, `processing`, `completed`, `failed`, `partial`.
platform	string	Filter to posts with at least one target on this platform: `instagram`, `threads`, `tiktok`, or `x`.

curl "https://api.omnipost.dev/v1/posts?status=failed&limit=10" \
  -H "Authorization: Bearer $OMNIPOST_API_KEY"

{
  "data": [
    {
      "id": "post_8f3d1a9c2b7e4f01",
      "status": "partial",
      "caption": "New drop is live 🚀",
      "created_at": "2026-08-02T14:03:11Z",
      "targets": [
        { "platform": "instagram", "status": "published", "external_url": "https://www.instagram.com/p/Cz1a2B3cD4e/" },
        { "platform": "x", "status": "failed", "error_code": "platform_rejected_media", "error_message": "Video exceeds 140 seconds." }
      ]
    }
  ],
  "next_cursor": "cur_7e2a9c1b8f4d4056",
  "has_more": true
}

Get a post

GET/v1/posts/:id

Returns a single post with its full target list, including any error detail.

curl https://api.omnipost.dev/v1/posts/post_8f3d1a9c2b7e4f01 \
  -H "Authorization: Bearer $OMNIPOST_API_KEY"

{
  "id": "post_8f3d1a9c2b7e4f01",
  "status": "completed",
  "caption": "New drop is live 🚀",
  "media": [
    { "url": "https://cdn.yourapp.com/campaign/hero.jpg", "type": "image" }
  ],
  "created_at": "2026-08-02T14:03:11Z",
  "targets": [
    {
      "platform": "instagram",
      "status": "published",
      "external_url": "https://www.instagram.com/p/Cz1a2B3cD4e/",
      "published_at": "2026-08-02T14:03:19Z"
    }
  ]
}

Target status values

Status	Meaning
pending	Queued, not yet started.
processing	Media upload / platform publish call in flight.
published	Live. `external_url` and `published_at` are set.
failed	`error_code` / `error_message` are set. See Errors.

The parent post.status is derived from its targets: pending/processing while any target is still in flight, completed once all targets published, failed if all targets failed, and partial if the targets have a mixed outcome.