# GET /v1/projects/:projectId/scheduled-posts (/docs/api/reference/publishing/list-scheduled-posts)



<Endpoint method="GET" path="/v1/projects/:projectId/scheduled-posts" auth="Bearer" scope="publish:read" phase="1" />

Enumerate scheduled posts on a project. Useful for populating a queue view in your UI, batch-polling terminal states after a bulk schedule, or reconciling against your own post ledger.

Paginates by `cursor`. Default sort is `scheduledFor` descending (most-recent-first), which matches a "recent activity" view — use `since`/`until` to window a queue.

<Parameters
  title="Path"
  rows="[
  { name: 'projectId', type: 'string', required: true, description: 'Project whose posts you want.' },
]"
/>

<Parameters
  title="Query"
  rows="[
  { name: 'status', type: 'string | string[]', description: 'One of queued, publishing, draft_in_inbox, published, failed, canceled. Repeat the parameter (e.g. `?status=queued&status=publishing`) to filter on multiple statuses.' },
  { name: 'socialAccountId', type: 'string', description: 'Scope to one connected account.' },
  { name: 'since', type: 'string (ISO-8601)', description: 'Inclusive lower bound on scheduledFor.' },
  { name: 'until', type: 'string (ISO-8601)', description: 'Inclusive upper bound on scheduledFor.' },
  { name: 'cursor', type: 'string', description: 'Opaque pagination cursor from a previous response.' },
  { name: 'limit', type: 'integer', description: 'Page size, 1–100.', default: '50' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl "https://api.layers.com/v1/projects/prj_01HX9Y7K8M2P4RSTUV56789AB/scheduled-posts?status=queued&status=publishing&limit=100" \
      -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..."
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    async function* walkAllPending(projectId: string) {
      let cursor: string | undefined;
      do {
        const page = await layers.publishing.listScheduledPosts({
          projectId,
          status: ["queued", "publishing"],
          limit: 100,
          cursor,
        });
        yield* page.items;
        cursor = page.nextCursor ?? undefined;
      } while (cursor);
    }
    ```
  </Tab>

  <Tab value="Python">
    ```python
    def walk_all_pending(project_id: str):
        cursor = None
        while True:
            page = layers.publishing.list_scheduled_posts(
                project_id=project_id,
                status=["queued", "publishing"],
                limit=100,
                cursor=cursor,
            )
            yield from page["items"]
            cursor = page.get("nextCursor")
            if not cursor:
                return
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="Page of posts">
  ```json
  {
    "items": [
      {
        "id": "sp_01HXZN4K5M6P7QRS8TUV9WXYZA",
        "containerId": "cnt_01HXZM3K4N5P6QRS7TUV8WXYZ9",
        "socialAccountId": "sa_01HXZ9P2M4N5KLM6TUV7WXYZ9A",
        "platform": "tiktok",
        "mode": "direct_publish",
        "status": "queued",
        "scheduledFor": "2026-04-19T14:00:00Z",
        "attemptedAt": null,
        "publishedAt": null,
        "externalUrl": null
      }
    ],
    "nextCursor": "cur_01HXZP8K9M4N5P6QRSTU"
  }
  ```
</Response>

## Errors [#errors]

| Status | Code              | When                                                         |
| ------ | ----------------- | ------------------------------------------------------------ |
| 422    | `VALIDATION`      | `since` > `until`, `limit` out of range, bad `status` value. |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                      |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `publish:write`.                                   |
| 404    | `NOT_FOUND`       | Project not in your organization.                            |

## See also [#see-also]

* [`GET /v1/scheduled-posts/:id`](/docs/api/reference/publishing/get-scheduled-post) — full status for one post
* [`POST /v1/scheduled-posts/:id/reschedule`](/docs/api/reference/publishing/reschedule-post) — reschedule