# List Posts ## 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](/api/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": [], "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"], "state": { "type": "published", "postUrl": "https://instagram.com/p/abc123" } }, { "id": "98430", "postTime": "2026-03-29T11:00:00.000Z", "platform": "tiktok", "text": "Failed upload", "mediaUrls": ["https://example.com/clip.mp4"], "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[].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" } ``` | Field | Type | Description | | --------- | ---------------- | ---------------------------------------------------------------------------- | | `postUrl` | `string \| null` | The live URL of the published post. Null if the platform did not return one. | **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: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.blotato.com/api/publish-post/list-posts.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.