List posts

GET /posts

Returns scheduled, published, or draft posts. Supports filtering by status and platform, with pagination.

Round-trip safe

Every post in the posts[] array has the same shape as a single post returned by GET /v1/posts/{post_id} and is round-trip safe with POST /v1/posts — pull a post down, mutate a field, POST it back to clone. Canonical field names: post_id, content, account_ids, scheduled_for, timezone, media_ids.

scheduled_for vs created_at

scheduled_for is a future timestamp — when the post will publish. created_at is a past timestamp — when the post record was created. Don't confuse them. All timestamps are UTC with a Z suffix.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by post status: `scheduled`, `published`, or `draft`
`platform`	string	No	Filter by destination platform (e.g. `instagram`, `linkedin`, `x`)
`limit`	integer	No	Number of posts to return. Min 1, max 100, default 20.
`offset`	integer	No	Number of posts to skip. Default 0.

Request Example

GET /posts?status=scheduled&platform=instagram&limit=10&offset=0

Response Example

200 — List of posts

{
  "data": {
    "posts": [
      {
        "post_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "scheduled",
        "content": "Excited to share our latest update!",
        "account_ids": [2280, 2282, 2285],
        "scheduled_for": "2026-04-15T14:30:00.000Z",
        "timezone": "America/New_York",
        "media_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
        "media": [
          {
            "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "type": "image",
            "width": 1920,
            "height": 1080
          }
        ],
        "platform_content": {},
        "destinations": [
          {
            "account_id": 2280,
            "account_name": "@mybrand",
            "platform": "instagram",
            "status": "queued",
            "platform_post_id": null,
            "platform_post_url": null,
            "published_at": null,
            "error": null,
            "attempts": 0
          }
        ],
        "created_at": "2026-04-10T12:00:00.000Z",
        "updated_at": "2026-04-10T12:00:00.000Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0
    }
  },
  "error": null,
  "meta": {
    "request_id": "a1b2c3d4",
    "timestamp": "2026-04-10T12:00:00.000Z"
  }
}

Post object fields

Field	Type	Description
`post_id`	string (UUID)	Canonical post identifier
`id`	string (UUID)	Deprecated alias for `post_id` (same value). Use `post_id` in new code.
`status`	string	`draft`, `scheduled`, `published`, or `failed`
`content`	string	Text content of the post
`account_ids`	integer[]	Target account IDs (round-trip safe against `POST /v1/posts`)
`scheduled_for`	string (ISO 8601) or null	UTC datetime when the post will publish (Z suffix)
`timezone`	string	IANA timezone — display metadata only
`media_ids`	string[] (UUID)	Convenience array of attached media UUIDs
`media`	object[] or null	Fully hydrated media objects with type and dimensions
`platform_content`	object	Per-platform overrides
`destinations`	object[]	One entry per target account — see below
`created_at`	string (ISO 8601)	UTC timestamp when the record was created
`updated_at`	string (ISO 8601)	UTC timestamp of most recent update

Destination object fields

Field	Type	Description
`account_id`	integer	Account ID (matches an entry in `account_ids`)
`account_name`	string or null	Display name or username
`platform`	string	Platform name (e.g. `instagram`, `x`, `linkedin`)
`status`	string	`queued`, `publishing`, `published`, or `failed`
`platform_post_id`	string or null	Platform's native post ID
`platform_post_url`	string or null	Direct URL to the published post
`published_at`	string (ISO 8601) or null	UTC timestamp of publish on this destination
`error`	string or null	Error message if failed
`attempts`	integer	Number of publish attempts

Request

Responses

List of posts

List posts

/posts

Query Parameters​

Request Example​

Response Example​

200 — List of posts​

Post object fields​

Destination object fields​

Request​

Responses​