Skip to content

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.

Query parameters field map
ParameterRequiredTypeAllowed values / formatDefaultDescription
originNostring"all" | "postpeer" | "external""all"Filter posts by where they were originally published.
statusNostring"draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"NoneFilter by post status.
platformNoarray<string>"twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"NoneFilter by platform (repeatable — OR logic).
profileIdNostringProfile identifier, or literal "null"NoneFilter to posts targeting an integration bound to this profile. Pass "null" (literal string) to filter to posts whose integrations have no profile.
createdAfterNostringISO 8601 date-timeNoneLower bound on createdAt.
createdBeforeNostringISO 8601 date-timeNoneUpper bound on createdAt.
scheduledAfterNostringISO 8601 date-timeNoneLower bound on scheduledFor.
scheduledBeforeNostringISO 8601 date-timeNoneUpper bound on scheduledFor.
limitNointeger1 <= value <= 10020Page size (max 100).
offsetNointeger0 <= value0Number of posts to skip.
sortNostring"asc" | "desc""desc"Sort direction by createdAt.

All parameters are optional per the captured contract.

200 response field map
FieldTypeDescription
successbooleanWhether the request succeeded.
totalintegerTotal number of posts matching the filters.
postsarrayPaginated list of post objects.
posts[].postIdstringIdentifier of the post.
posts[].originstringWhere the post was originally published.
posts[].isExternalbooleanWhether the post originated externally.
posts[].externalSource.accountIdstringAccount identifier for the external source.
posts[].externalSource.platformPostIdstringPlatform post identifier for the external source.
posts[].externalSource.mediaTypestringMedia type for the external source.
posts[].externalSource.thumbnailUrlstringThumbnail URL for the external source.
posts[].externalSource.lastSyncedAtstringLast sync timestamp for the external source.
posts[].titlestringPost title.
posts[].contentstringPost content.
posts[].statusstringPost status.
posts[].scheduledForstringScheduled timestamp for the post.
posts[].timezonestringTimezone associated with the post.
posts[].mediaItems[].typestringMedia item type.
posts[].mediaItems[].urlstringMedia item URL.
posts[].mediaItems[].altTextstringAlternative text for the media item.
posts[].mediaItems[].filenamestringMedia item filename.
posts[].mediaItems[].sizeintegerMedia item size.
posts[].mediaItems[].mimeTypestringMedia item MIME type.
posts[].platforms[].platformstringTarget platform.
posts[].platforms[].statusstringPer-platform status.
posts[].platforms[].contentstringPer-platform content.
posts[].platforms[].platformPostIdstringPer-platform post identifier.
posts[].platforms[].platformPostUrlstringPer-platform post URL, included for published posts.
posts[].platforms[].publishedAtstringPer-platform publish timestamp.
posts[].platforms[].errorMessagestringPer-platform error message.
posts[].platforms[].warningMessagestringPer-platform warning message.
posts[].crosspostingEnabledbooleanWhether crossposting is enabled for the post.
posts[].rawRequestBodyobjectRaw request body captured for the post.
posts[].createdAtstringCreation timestamp.
posts[].updatedAtstringLast update timestamp.

Field types are as shown in the captured 200 example; nested objects are described by their captured fields.

Filtering, pagination, and edge cases
CaseInputExpected behaviorCheck
No profile filterOmit profileIdNo profile filtering is applied.Confirm total includes profiled and unprofiled posts.
Unprofiled posts onlyprofileId=null (literal string)Returns posts whose integrations have no profile.Do not send an empty value or a JSON null.
Multiple platformsplatform=twitter&platform=linkedinOR logic returns posts matching either platform.Confirm the result is a union, not an intersection.
Creation windowcreatedAfter and createdBefore as ISO 8601 date-timeBounds results on createdAt.Use date-time format, not a bare date.
Scheduled windowscheduledAfter and scheduledBefore as ISO 8601 date-timeBounds results on scheduledFor.Use date-time format, not a bare date.
Page size too largelimit above 100Outside the allowed range 1 <= value <= 100.Reduce limit to at most 100.
Negative offsetoffset below 0Outside the allowed range 0 <= value.Use offset 0 or a positive integer.
Second pagelimit=20&offset=20Skips 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.

List posts with combined filters and pagination
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>"
200 response body example
{
  "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"
    }
  ]
}
400 response body example
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
origin#1originstring__0NoFilter posts by where they were originally published.kind: schemaDefault; value: "all"
origin#1origin[variant1]string__0_extends:__1Filter posts by where they were originally published.kind: schemaDefault; value: "all" | kind: schemaValueIn; value: "all"
origin#1origin[variant2]string__0_extends:__2Filter posts by where they were originally published.kind: schemaDefault; value: "all" | kind: schemaValueIn; value: "postpeer"
origin#1origin[variant3]string__0_extends:__3Filter posts by where they were originally published.kind: schemaDefault; value: "all" | kind: schemaValueIn; value: "external"
status#2statusstring__0Nokind: schemaValueIn; value: "draft" | "pending" | "scheduled" | "publishing" | "published" | "failed" | "partial"
platform#3platformarray<string>__0NoFilter by platform (repeatable — OR logic)
platform#3platform[]string__1kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
profileId#4profileIdstring__0NoFilter to posts targeting an integration bound to this profile. Pass "null" (literal string) to filter to posts whose integrations have no profile.
createdAfter#5createdAfterstring__0NoISO 8601 lower bound on createdAtkind: schemaFormat; value: date-time
createdBefore#6createdBeforestring__0NoISO 8601 upper bound on createdAtkind: schemaFormat; value: date-time
scheduledAfter#7scheduledAfterstring__0NoISO 8601 lower bound on scheduledForkind: schemaFormat; value: date-time
scheduledBefore#8scheduledBeforestring__0NoISO 8601 upper bound on scheduledForkind: schemaFormat; value: date-time
limit#9limitinteger__0NoPage size (max 100)kind: schemaDefault; value: 20 | kind: schemaRange; value: 1 <= value <= 100
offset#10offsetinteger__0NoNumber of posts to skipkind: schemaDefault; value: 0 | kind: schemaRange; value: 0 <= value
sort#11sortstring__0NoSort direction by createdAtkind: schemaDefault; value: "desc" | kind: schemaValueIn; value: "asc" | "desc"
response#12responseobject__0
response#12response.successboolean__1Yes
response#12response.messagestring__2Yes