Skip to content

List Posts API

The List Posts API retrieves a paginated list of posts with filtering and sorting. Use it to find posts by status, platform, creation time, or scheduled time, then page through matching results in a predictable order.

Endpoint and operation summary

The List Posts API retrieves a paginated list of posts with filtering and sorting. Use it when you need to find posts by status, platform, creation time, or scheduled time, then page through the matching results in a predictable order. The endpoint is shown in the List posts endpoint code example. Send the request with the x-access-key header shown in the worked example, and treat the query parameters below as the complete input contract for this operation.

Query parameter field map

Every query parameter is optional, but each one narrows or orders the result set in a specific way. The status parameter filters by a single post status. The platform parameter is repeatable and uses OR logic, so repeating it widens the result set to posts matching any listed platform rather than requiring all of them. The createdAfter and createdBefore parameters bound the createdAt timestamp, while scheduledAfter and scheduledBefore bound the scheduledFor timestamp, and all four accept ISO 8601 values. The limit parameter controls page size, offset controls how many posts to skip, and sort controls the order by createdAt. The full field map, including types, defaults, enums, and ranges, is in the Query parameters table.

Filtering and sorting decision guide

Choose filters by the question you are answering. Use status when you need one lifecycle state, such as published posts for a review queue or failed posts for follow-up. Use platform when you need posts for one or more destinations, repeating the parameter for each platform and remembering that the logic is OR. Use createdAfter and createdBefore to bound when a post was created, and scheduledAfter and scheduledBefore to bound its scheduledFor value, for example when auditing a scheduling window. Combine a date bound with status and platform when the window applies only to a subset. For pagination, set limit to the page size you want to process, between 1 and 100, and advance offset by that page size on each subsequent request. Use sort set to asc when you want oldest first, and desc, the default, when you want newest first. A common failure check is to confirm that limit stays within 1 to 100, that date values are valid ISO 8601 strings, and that status uses one of the documented enum values before retrying a request that returns 400.

Worked request example

The worked example in the List published posts for one platform code example requests published posts for twitter with a limit of 5. That single request combines a status filter, a platform filter, and a page size, which is the smallest useful shape for testing the endpoint before adding date bounds or offset paging. After sending the request, check the response status code first, then inspect the success flag and the posts array. If the request returns 400, the query parameters are invalid, so re-check the status enum, the limit range, and the ISO 8601 date formats rather than changing the endpoint path.

Response field map

A successful response contains a success flag, a total count, and a posts array, as shown in the List posts response example code example. Each post in the array carries its postId, content, status, scheduledFor, timezone, mediaItems, platforms, crosspostingEnabled, createdAt, and updatedAt fields. The nested platforms array describes each platform target for that post, including platform, status, platformPostId, platformPostUrl, publishedAt, and errorMessage. Use platformPostId and platformPostUrl to link a post back to its published destination, and check the per-platform errorMessage when a target did not publish cleanly even though the overall request succeeded. The full response field map is in the Response fields table.

Status codes and failure checks

The endpoint returns 200 on success and 400 when query parameters are invalid. Treat 200 as confirmation that the list request was accepted and that the response body should be parsed for success, total, and posts. Treat 400 as a client-side correction signal: validate status, platform, the four date bounds, limit, offset, and sort against the Query parameters table, then resend the corrected request. Do not assume additional status codes beyond those documented for this operation.

Query parameters
ParameterTypeDefaultDescription
statusstring—Filter by status: "draft", "scheduled", "published", "failed", or "partial"
platformstring[]—Filter by platform (repeatable, OR logic). e.g. ?platform=twitter&platform=instagram
createdAfterstring—ISO 8601 lower bound on createdAt
createdBeforestring—ISO 8601 upper bound on createdAt
scheduledAfterstring—ISO 8601 lower bound on scheduledFor
scheduledBeforestring—ISO 8601 upper bound on scheduledFor
limitinteger20Page size (1–100)
offsetinteger0Number of posts to skip
sortstring"desc"Sort by createdAt: "asc" or "desc"

Exact source contract; origin modularized as {{API_BASE_URL}}.

Response fields
FieldType / shapeDescription
successbooleanWhether the request succeeded
totalintegerTotal count in the example response: 42
postsarrayArray of post objects
postIdstringIdentifier for the post, e.g. "post_abc123"
contentstringPost content, e.g. "Hello world!"
statusstringPost status, e.g. "published"
scheduledForstring or nullScheduled time, or null when not scheduled
timezonestringTimezone, e.g. "UTC"
mediaItemsarrayMedia items attached to the post
platformsarrayPer-platform target results for the post
platforms[].platformstringPlatform name, e.g. "twitter"
platforms[].statusstringPer-platform status, e.g. "published"
platformPostIdstringPer-platform published post identifier, e.g. "1234567890"
platformPostUrlstringPer-platform published post URL
platforms[].publishedAtstringPer-platform publish timestamp
platforms[].errorMessagestring or nullPer-platform error message, or null
crosspostingEnabledbooleanWhether crossposting is enabled for the post
createdAtstringCreation timestamp
updatedAtstringLast update timestamp

Shape preserved from the source worked response example.

Status codes
CodeMeaning
200Success
400Invalid query parameters

Only status codes supplied in the source contract.

List published posts for one platform
curl "{{API_BASE_URL}}/v1/posts?status=published&platform=twitter&limit=5" \
  -H "x-access-key: YOUR_API_KEY"
Contract example 1
GET {{API_BASE_URL}}/v1/posts
Contract example 5
{
	"success": true,
	"total": 42,
	"posts": [
		{
			"postId": "post_abc123",
			"content": "A short example update.",
			"status": "published",
			"scheduledFor": null,
			"timezone": "UTC",
			"mediaItems": [],
			"platforms": [
				{
					"platform": "twitter",
					"status": "published",
					"platformPostId": "1234567890",
					"platformPostUrl": "https://twitter.com/you/status/1234567890",
					"publishedAt": "2026-04-15T14:30:00.000Z",
					"errorMessage": null
				}
			],
			"crosspostingEnabled": false,
			"createdAt": "2026-04-15T14:30:00.000Z",
			"updatedAt": "2026-04-15T14:30:01.000Z"
		}
	]
}