List Posts API
The List Posts API returns a paginated list of posts for a project. You can narrow the result set by origin, status, platform, profile, creation date, and scheduled date, then control page size, offset, and sort direction. Published posts include platformPostUrl per platform, so callers can link each platform result back to the live post without a second lookup.
List Posts API endpoint overview
Use GET /v1/posts/ to retrieve a paginated list of posts. The endpoint supports filtering by status, platform with OR logic, and date ranges, and published posts include platformPostUrl per platform. Every query parameter is optional, which makes the bare request useful for a first page and makes each filter safe to add incrementally as the caller narrows the result set.
Authorization
Send the access key in the x-access-key header. The header name is accessKey in the source contract and the value is supplied as <token> in the header. Keep the token out of query strings and logs, and treat a missing or invalid key as an authorization failure to check before debugging filters or pagination.
Query Parameters field map
All query parameters are optional. The origin parameter filters by where posts were originally published and defaults to all, with all, postpeer, and external as the allowed values. The status parameter accepts draft, pending, scheduled, publishing, published, failed, or partial. The platform parameter is repeatable and uses OR logic, accepting twitter, instagram, youtube, tiktok, pinterest, linkedin, bluesky, facebook, threads, or googlebusiness. The profileId parameter filters to posts targeting an integration bound to that profile, and the literal string null filters to posts whose integrations have no profile. Use createdAfter and createdBefore as ISO 8601 lower and upper bounds on createdAt, and scheduledAfter and scheduledBefore as ISO 8601 lower and upper bounds on scheduledFor. Page size is controlled by limit, an integer from 1 to 100 defaulting to 20, and offset, an integer greater than or equal to 0 defaulting to 0. Sort direction by createdAt is controlled by sort, which accepts asc or desc and defaults to desc. The worked example titled List posts with combined filters and pagination shows these parameters together without changing their semantics.
200 application/json response field map
A successful call returns HTTP 200 with application/json. The body contains success as a boolean, total as the count for the filtered result set, and posts as an array of post objects. Each post object carries postId, origin, isExternal, externalSource, title, content, status, scheduledFor, timezone, mediaItems, platforms, crosspostingEnabled, rawRequestBody, createdAt, and updatedAt. The externalSource object carries accountId, platformPostId, mediaType, thumbnailUrl, and lastSyncedAt. Each mediaItems entry carries type, url, altText, filename, size, and mimeType. Each platforms entry carries platform, status, content, platformPostId, platformPostUrl, publishedAt, errorMessage, and warningMessage. The 200 response body example shows the full nested shape, including crosspostingEnabled and platformPostUrl, so client code can be generated against exact field names.
400 application/json response handling
A rejected request returns HTTP 400 with application/json. The captured contract does not fully specify the 400 body shape, so client code should branch on the status code and should not depend on invented error fields. The 400 response body example preserves the only captured body shape available for this status. When a 400 occurs, recheck enum values, date-time formats, and the limit and offset ranges before retrying, because those are the constraints most likely to be violated by a hand-built query string.
Pagination, filtering, and sorting decision guide
Start with the defaults for a simple browse view, then add one filter at a time and confirm the total changes as expected. Use status to isolate a workflow stage, repeat platform for OR logic across networks, and profileId with the literal null to find unprofiled posts. Use createdAfter and createdBefore to audit what was created in a window, and scheduledAfter and scheduledBefore to audit what was scheduled in a window. Increase limit up to 100 for bulk exports, advance offset in steps of the chosen limit for later pages, and switch sort to asc when chronological order matters. Check the failure and edge cases in the table titled Filtering, pagination, and edge cases before shipping, especially the literal null profileId, repeatable platform values, and out-of-range limit values.
| Parameter | Required | Type | Allowed values / format | Default | Description |
|---|---|---|---|---|---|
| origin | No | string | "all" | "postpeer" | "external" | "all" | Filter posts by where they were originally published. |
| status | No | string | "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial" | None | Filter by post status. |
| platform | No | array<string> | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | None | Filter by platform (repeatable — OR logic). |
| profileId | No | string | Profile identifier, or literal "null" | None | Filter to posts targeting an integration bound to this profile. Pass "null" (literal string) to filter to posts whose integrations have no profile. |
| createdAfter | No | string | ISO 8601 date-time | None | Lower bound on createdAt. |
| createdBefore | No | string | ISO 8601 date-time | None | Upper bound on createdAt. |
| scheduledAfter | No | string | ISO 8601 date-time | None | Lower bound on scheduledFor. |
| scheduledBefore | No | string | ISO 8601 date-time | None | Upper bound on scheduledFor. |
| limit | No | integer | 1 <= value <= 100 | 20 | Page size (max 100). |
| offset | No | integer | 0 <= value | 0 | Number of posts to skip. |
| sort | No | string | "asc" | "desc" | "desc" | Sort direction by createdAt. |
All parameters are optional per the captured contract.
| Field | Type | Description |
|---|---|---|
| success | boolean | Whether the request succeeded. |
| total | integer | Total number of posts matching the filters. |
| posts | array | Paginated list of post objects. |
| posts[].postId | string | Identifier of the post. |
| posts[].origin | string | Where the post was originally published. |
| posts[].isExternal | boolean | Whether the post originated externally. |
| posts[].externalSource.accountId | string | Account identifier for the external source. |
| posts[].externalSource.platformPostId | string | Platform post identifier for the external source. |
| posts[].externalSource.mediaType | string | Media type for the external source. |
| posts[].externalSource.thumbnailUrl | string | Thumbnail URL for the external source. |
| posts[].externalSource.lastSyncedAt | string | Last sync timestamp for the external source. |
| posts[].title | string | Post title. |
| posts[].content | string | Post content. |
| posts[].status | string | Post status. |
| posts[].scheduledFor | string | Scheduled timestamp for the post. |
| posts[].timezone | string | Timezone associated with the post. |
| posts[].mediaItems[].type | string | Media item type. |
| posts[].mediaItems[].url | string | Media item URL. |
| posts[].mediaItems[].altText | string | Alternative text for the media item. |
| posts[].mediaItems[].filename | string | Media item filename. |
| posts[].mediaItems[].size | integer | Media item size. |
| posts[].mediaItems[].mimeType | string | Media item MIME type. |
| posts[].platforms[].platform | string | Target platform. |
| posts[].platforms[].status | string | Per-platform status. |
| posts[].platforms[].content | string | Per-platform content. |
| posts[].platforms[].platformPostId | string | Per-platform post identifier. |
| posts[].platforms[].platformPostUrl | string | Per-platform post URL, included for published posts. |
| posts[].platforms[].publishedAt | string | Per-platform publish timestamp. |
| posts[].platforms[].errorMessage | string | Per-platform error message. |
| posts[].platforms[].warningMessage | string | Per-platform warning message. |
| posts[].crosspostingEnabled | boolean | Whether crossposting is enabled for the post. |
| posts[].rawRequestBody | object | Raw request body captured for the post. |
| posts[].createdAt | string | Creation timestamp. |
| posts[].updatedAt | string | Last update timestamp. |
Field types are as shown in the captured 200 example; nested objects are described by their captured fields.
| Case | Input | Expected behavior | Check |
|---|---|---|---|
| No profile filter | Omit profileId | No profile filtering is applied. | Confirm total includes profiled and unprofiled posts. |
| Unprofiled posts only | profileId=null (literal string) | Returns posts whose integrations have no profile. | Do not send an empty value or a JSON null. |
| Multiple platforms | platform=twitter&platform=linkedin | OR logic returns posts matching either platform. | Confirm the result is a union, not an intersection. |
| Creation window | createdAfter and createdBefore as ISO 8601 date-time | Bounds results on createdAt. | Use date-time format, not a bare date. |
| Scheduled window | scheduledAfter and scheduledBefore as ISO 8601 date-time | Bounds results on scheduledFor. | Use date-time format, not a bare date. |
| Page size too large | limit above 100 | Outside the allowed range 1 <= value <= 100. | Reduce limit to at most 100. |
| Negative offset | offset below 0 | Outside the allowed range 0 <= value. | Use offset 0 or a positive integer. |
| Second page | limit=20&offset=20 | Skips the first 20 matching posts. | Advance offset by the chosen limit each page. |
Behavior is limited to the captured contract; no additional error fields are assumed.
Frequently asked questions
What is the minimum request for the List Posts API?
Send GET /v1/posts/ with the x-access-key header. All query parameters are optional, so a request with no parameters returns the first page using the defaults limit 20, offset 0, sort desc, and origin all.
How do I filter by more than one platform?
Repeat the platform parameter, for example platform=twitter&platform=linkedin. The filter uses OR logic, so posts matching any listed platform are included.
How do I filter for posts with no profile?
Pass the literal string null as the profileId value. That is different from omitting profileId, which applies no profile filter.
Which parameters bound creation and scheduled dates?
Use createdAfter and createdBefore for bounds on createdAt, and scheduledAfter and scheduledBefore for bounds on scheduledFor. All four values use ISO 8601 date-time format.
How do the 200 and 400 responses differ?
A 200 response contains success, total, and a posts array. A 400 response uses application/json, but its body shape is not fully specified in the captured contract, so do not rely on invented error fields.
curl -X GET "{{API_BASE_URL}}/v1/posts/?status=scheduled&platform=twitter&platform=linkedin&createdAfter=2026-01-01T00:00:00Z&scheduledBefore=2026-02-01T00:00:00Z&limit=20&offset=0&sort=desc" -H "x-access-key: <token>"{
"success": true,
"total": 0,
"posts": [
{
"postId": "string",
"origin": "postpeer",
"isExternal": true,
"externalSource": {
"accountId": "string",
"platformPostId": "string",
"mediaType": "image",
"thumbnailUrl": "string",
"lastSyncedAt": "2019-08-24T14:15:22Z"
},
"title": "string",
"content": "string",
"status": "draft",
"scheduledFor": "2019-08-24T14:15:22Z",
"timezone": "string",
"mediaItems": [
{
"type": "image",
"url": "string",
"altText": "string",
"filename": "string",
"size": 0,
"mimeType": "string"
}
],
"platforms": [
{
"platform": "twitter",
"status": "draft",
"content": "string",
"platformPostId": "string",
"platformPostUrl": "string",
"publishedAt": "2019-08-24T14:15:22Z",
"errorMessage": "string",
"warningMessage": "string"
}
],
"crosspostingEnabled": true,
"rawRequestBody": {},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| origin#1 | origin | string | __0 | No | Filter posts by where they were originally published. | kind: schemaDefault; value: "all" |
| origin#1 | origin[variant1] | string | __0_extends:__1 | Filter posts by where they were originally published. | kind: schemaDefault; value: "all" | kind: schemaValueIn; value: "all" | |
| origin#1 | origin[variant2] | string | __0_extends:__2 | Filter posts by where they were originally published. | kind: schemaDefault; value: "all" | kind: schemaValueIn; value: "postpeer" | |
| origin#1 | origin[variant3] | string | __0_extends:__3 | Filter posts by where they were originally published. | kind: schemaDefault; value: "all" | kind: schemaValueIn; value: "external" | |
| status#2 | status | string | __0 | No | kind: schemaValueIn; value: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial" | |
| platform#3 | platform | array<string> | __0 | No | Filter by platform (repeatable — OR logic) | |
| platform#3 | platform[] | string | __1 | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | ||
| profileId#4 | profileId | string | __0 | No | Filter to posts targeting an integration bound to this profile. Pass "null" (literal string) to filter to posts whose integrations have no profile. | |
| createdAfter#5 | createdAfter | string | __0 | No | ISO 8601 lower bound on createdAt | kind: schemaFormat; value: date-time |
| createdBefore#6 | createdBefore | string | __0 | No | ISO 8601 upper bound on createdAt | kind: schemaFormat; value: date-time |
| scheduledAfter#7 | scheduledAfter | string | __0 | No | ISO 8601 lower bound on scheduledFor | kind: schemaFormat; value: date-time |
| scheduledBefore#8 | scheduledBefore | string | __0 | No | ISO 8601 upper bound on scheduledFor | kind: schemaFormat; value: date-time |
| limit#9 | limit | integer | __0 | No | Page size (max 100) | kind: schemaDefault; value: 20 | kind: schemaRange; value: 1 <= value <= 100 |
| offset#10 | offset | integer | __0 | No | Number of posts to skip | kind: schemaDefault; value: 0 | kind: schemaRange; value: 0 <= value |
| sort#11 | sort | string | __0 | No | Sort direction by createdAt | kind: schemaDefault; value: "desc" | kind: schemaValueIn; value: "asc" | "desc" |
| response#12 | response | object | __0 | |||
| response#12 | response.success | boolean | __1 | Yes | ||
| response#12 | response.message | string | __2 | Yes |