> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Posts

> Fetch recent Partner API posts with delivery status and summary. Track your automated posting pipeline across supported platforms.

Fetch the latest posts in key scope along with a summary, or read one calendar window of posts by
their scheduled time. Use this to track delivery status across supported platforms, including posts
scheduled by your OpenClaw agent or automation scripts, or to build a content calendar.

<Note>
  Only posts that include deliveries for accounts owned by the authenticated key scope are returned.
  Hosted and BYO accounts are both supported, and deliveries for accounts outside scope are filtered
  out automatically.
</Note>

## Query Parameters

<ParamField query="status" type="string">
  Filter by status: `draft`, `pending`, `scheduled`, `posted`, `failed`, `partial`, `retry`,
  `canceled`. When omitted, all statuses are returned.
</ParamField>

<ParamField query="statuses" type="string">
  Several statuses, comma-separated (for example `scheduled,posted`). Use `status` or `statuses`,
  not both.
</ParamField>

<ParamField query="limit" type="number" default="100">
  Number of posts to return. Values below 1 are treated as 1; values above 100 are clamped to 100.
</ParamField>

<ParamField query="offset" type="number" default="0">
  How many posts to skip, for the next page.
</ParamField>

<ParamField query="scheduled_from" type="string">
  Start of a calendar window: ISO 8601 with offset. Only posts scheduled at or after this time.
  Send it with `scheduled_until`.
</ParamField>

<ParamField query="scheduled_until" type="string">
  End of the calendar window (inclusive), at most 62 days after `scheduled_from`.
</ParamField>

<ParamField query="account_ids" type="string">
  Only posts going to these account ids, comma-separated (up to 50). Ids outside the key scope
  match nothing.
</ParamField>

<ParamField query="sort" type="string" default="created_at">
  `created_at` (newest first) or `scheduled_time` (earliest scheduled first, for a calendar).
</ParamField>

<ParamField query="since" type="string">
  ISO timestamp. Only include posts created on or after this time.
</ParamField>

<ParamField query="until" type="string">
  ISO timestamp. Only include posts created on or before this time.
</ParamField>

<Warning>
  `since` and `until` must be valid ISO 8601 strings. Invalid values return a `400` response with
  `error_code` set to `invalid_since` or `invalid_until`. A calendar window that is missing an end,
  reversed, or longer than 62 days returns `400 invalid_scheduled_window`.
</Warning>

<Tip>
  A week of a content calendar is one request: `scheduled_from` and `scheduled_until` around the
  week, `sort=scheduled_time` and `limit=100`.
</Tip>

## Response

Returns a `summary` object with counts and a `posts` array.

<ResponseField name="summary" type="object">
  Scope-wide counters.

  <Expandable title="Summary Object">
    <ResponseField name="total" type="number" />

    <ResponseField name="pending" type="number" />

    <ResponseField name="published" type="number" />

    <ResponseField name="by_status" type="object" />
  </Expandable>
</ResponseField>

<ResponseField name="posts" type="array">
  List of post objects. Each post may include `tiktok` and/or `pinterest` settings when those
  platform-specific payloads were provided at create/update time, and `settings` with the stored
  `settings.<provider>` objects. `media` is `null` for text-only posts. Each entry of
  `accounts.states` names the destination's `platform` and `username`.
</ResponseField>

<Note>
  `summary.by_status` tracks canonical lifecycle buckets (`draft`, `pending`, `scheduled`, `posted`,
  `partial`, `failed`). Provider-facing statuses (for example `deleted`/`void`) can still appear on
  individual post/account `status` fields and are included in `summary.total`.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://www.genviral.io/api/partner/v1/posts?status=scheduled&limit=20' \
    --header 'Authorization: Bearer <token>'
  ```

  ```bash Calendar week theme={null}
  curl --request GET \
    --url 'https://www.genviral.io/api/partner/v1/posts?scheduled_from=2026-10-05T00:00:00%2B02:00&scheduled_until=2026-10-11T23:59:59%2B02:00&sort=scheduled_time&limit=100' \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Posts retrieved",
    "data": {
      "summary": {
        "total": 193,
        "pending": 58,
        "published": 120,
        "by_status": {
          "draft": 15,
          "pending": 12,
          "scheduled": 46,
          "posted": 118,
          "failed": 4
        }
      },
      "posts": [
        {
          "id": "11111111-1111-1111-1111-111111111111",
          "caption": "Holiday drops start Monday!",
          "status": "deleted",
          "scheduled_at": "2025-02-01T15:00:00Z",
          "created_at": "2025-01-20T12:05:11.205Z",
          "media": null,
          "music_url": null,
          "tiktok": null,
          "pinterest": {
            "board_id": "123456789012345678",
            "title": "Dinner board",
            "tags": ["Italian recipes"]
          },
          "settings": null,
          "accounts": {
            "total": 2,
            "states": [
              {
                "account_id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
                "platform": "pinterest",
                "username": "dinnerboard",
                "status": "deleted",
                "published_at": null,
                "error_message": null,
                "last_attempted_at": null,
                "published_url": null
              },
              {
                "account_id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089",
                "platform": "tiktok",
                "username": "dinnerclub",
                "status": "scheduled",
                "published_at": null,
                "error_message": null,
                "last_attempted_at": null,
                "published_url": null
              }
            ]
          }
        }
      ]
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 invalid_since` or `400 invalid_until` - query params failed ISO parsing
* `400 invalid_scheduled_window` - a calendar window is missing an end, reversed, or longer than 62 days
* `400 invalid_statuses`, `400 invalid_account_ids`, `400 invalid_sort`, `400 invalid_offset` - a filter value is not allowed
* `401` - authentication failed (missing/invalid/revoked token)
* `402 subscription_required` - active Creator/Professional/Business plan required
* `403 tier_not_allowed` - Scheduler tier cannot use Partner API
* `500 list_failed` - Database query or summary computation failed


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.