> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/rest-api-reference/publish-post/list-posts.md). # List Posts Find scheduled, published, or failed posts using date, platform, status, and pagination filters. ## List Posts ### Endpoint **Base URL:** `https://backend.blotato.com/v2` **URL:** `/posts` **Method:** `GET` **Rate Limit:** 60 requests / minute ### Description Returns the current user's posts (scheduled, published, and failed) within a time window, ordered by post time (most recent first). Supports cursor-based pagination and filtering by status and platform. To check the status of a single post by its `postSubmissionId`, use [Get Post Status](/rest-api-reference/publish-post/get-post.md) instead. ### Query Parameters | Field | Type | Required | Description | | ---------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `since` | `string` | No | Only include posts whose post time is on or after this ISO 8601 timestamp. Defaults to 7 days ago. | | `until` | `string` | No | Only include posts whose post time is on or before this ISO 8601 timestamp. Defaults to 7 days from now. | | `limit` | `integer` | No | Number of items per page. Min: 1, Max: 250. Default: 50. | | `cursor` | `string` | No | Pagination cursor from a previous response. Pass it to fetch the next page. | | `status` | `string[]` | No | Filter by status. One or more of `scheduled`, `published`, `failed`. Pass multiple values to include any of them. Omit to include all statuses. | | `platform` | `string[]` | No | Filter by social media platform. One or more of `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube`. Pass multiple values to include any of them. Omit to include all platforms. | Array query parameters are repeated, e.g. `?status=scheduled&status=published`. ### Response **Status Code:** `200 OK` ```json { "items": [ { "id": "98432", "postTime": "2026-04-01T14:00:00.000Z", "platform": "twitter", "text": "Scheduled post content", "mediaUrls": [], "account": { "id": "123", "name": "Blotato", "subaccount": null }, "state": { "type": "scheduled" } }, { "id": "98431", "postTime": "2026-03-30T09:15:00.000Z", "platform": "instagram", "text": "Check out this image!", "mediaUrls": ["https://example.com/image1.jpg"], "account": { "id": "456", "name": "Blotato", "subaccount": null }, "state": { "type": "published", "postUrl": "https://instagram.com/p/abc123", "analytics": { "latest": { "fetchedAt": "2026-09-30T12:00:00Z", "metrics": { "viewsCount": "18400", "likesCount": "920" } }, "history": [] } } }, { "id": "98430", "postTime": "2026-03-29T11:00:00.000Z", "platform": "tiktok", "text": "Failed upload", "mediaUrls": ["https://example.com/clip.mp4"], "account": null, "state": { "type": "failed", "errorMessage": "Unsupported media type" } } ], "cursor": "MjAyNi0wMy0yOVQxMTowMDow..." } ``` #### Response Keys | Field | Type | Description | | ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `items` | `array` | List of posts within the time window, ordered by `postTime` descending. | | `items[].id` | `string` | The post's identifier. Distinct per `state.type`: scheduled posts use the schedule ID, published posts use the published post ID, failed posts use the failed post ID. | | `items[].postTime` | `string` | ISO 8601 UTC timestamp. For scheduled posts this is the planned publish time; for published posts it is when the post was published; for failed posts it is when the failure was recorded. | | `items[].platform` | `string` | Social media platform. | | `items[].text` | `string` | The post text. | | `items[].mediaUrls` | `string[]` | URLs of attached media (images, video). Empty when text-only. | | `items[].account` | `object or null` | Connected account with `id`, `name`, and `subaccount`. Null if the account is no longer connected. | | `items[].state` | `object` | Discriminated union; see below. | | `cursor` | `string` | Pagination cursor. Pass this as the `cursor` query parameter to fetch the next page. Absent when there are no more pages. | #### `state` object The shape depends on `state.type`: **Scheduled** ```json { "type": "scheduled" } ``` **Published** ```json { "type": "published", "postUrl": "https://instagram.com/p/abc123", "analytics": null } ``` | Field | Type | Description | | ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `postUrl` | `string \| null` | The live URL of the published post. Null if the platform did not return one. | | `analytics` | `object \| null` | Latest snapshot under `latest` and every snapshot, oldest first, under `history`. Null if metrics have not been collected or analytics is unavailable. | **Failed** ```json { "type": "failed", "errorMessage": "Unsupported media type" } ``` | Field | Type | Description | | -------------- | ---------------- | ------------------------------------------ | | `errorMessage` | `string \| null` | Human-readable description of the failure. | ### Errors | Status | Reason | | ------ | -------------------------------------------- | | `422` | Invalid `since`, `until`, or `cursor` value. | ### Examples #### Default request ```http GET https://backend.blotato.com/v2/posts HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Only published Twitter posts in the last 30 days ```http GET https://backend.blotato.com/v2/posts?since=2026-04-12T00:00:00Z&status=published&platform=twitter HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Scheduled or published, multi-platform ```http GET https://backend.blotato.com/v2/posts?status=scheduled&status=published&platform=twitter&platform=instagram HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` #### Walking pages ```http GET https://backend.blotato.com/v2/posts?limit=100 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` If the response contains a `cursor`, pass it on the next request: ```http GET https://backend.blotato.com/v2/posts?limit=100&cursor=MjAyNi0wMy0yOVQxMTowMDow... HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` When the response omits `cursor`, you have reached the end of the list. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.blotato.com/rest-api-reference/publish-post/list-posts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.