> ## 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. Use this to track delivery status across supported platforms, including posts scheduled by your OpenClaw agent or automation scripts.

<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`. When
  omitted, all statuses are returned.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of posts to return. Values below 1 are treated as 1; values above 100 are clamped to 100.
</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`.
</Warning>

## 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. `media` is `null` for text-only
  posts.
</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>'
  ```
</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"]
          },
          "accounts": {
            "total": 2,
            "states": [
              {
                "account_id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
                "status": "deleted",
                "published_at": null,
                "error_message": null,
                "last_attempted_at": null,
                "published_url": null
              },
              {
                "account_id": "6b0c8c9c-55ac-4fcb-85ec-70b5a8b0d089",
                "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
* `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