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 instead.
Query Parameters
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
Response Keys
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
state objectThe shape depends on state.type:
Scheduled
Published
postUrl
string | null
The live URL of the published post. Null if the platform did not return one.
Failed
errorMessage
string | null
Human-readable description of the failure.
Errors
422
Invalid since, until, or cursor value.
Examples
Default request
Only published Twitter posts in the last 30 days
Scheduled or published, multi-platform
Walking pages
If the response contains a cursor, pass it on the next request:
When the response omits cursor, you have reached the end of the list.
Last updated