List posts

List all posts in the workspace with pagination and filtering. Archived posts are excluded from results.

GET/posts

Authorization

AuthorizationBearer token · headerrequired

API key authentication. Generate an API key from your workspace settings.

Query parameters

limitinteger

Maximum number of posts to return (1-100)

min 1 · max 100 · default: 20

cursorstring<uuid>

Cursor for pagination (post ID from the last item of previous page)

idsstring<uuid> | string<uuid>[]

Fetch specific posts by IDs. Can be a single UUID or comma-separated list.

statusPostStatus

Filter by post status

Allowed:TentativeToDoInProgressForReviewBlockedFinalizedScheduledPosted

channelstring

Filter by channel

Allowed:LinkedInTwitterInstagramTikTokYouTubeShorts

linkedInProfileIdstring<uuid>

Filter by LinkedIn profile ID

xProfileIdstring<uuid>

Filter by X/Twitter profile ID

instagramProfileIdstring<uuid>

Filter by Instagram profile ID

tikTokProfileIdstring<uuid>

Filter by TikTok profile ID

youTubeProfileIdstring<uuid>

Filter by YouTube channel profile ID

labelIdsstring<uuid> | string<uuid>[]

Filter by label IDs (posts with any of these labels). Can be a single UUID or comma-separated list.

publishDateMinstring<date-time>

Filter posts scheduled on or after this date (ISO 8601 format)

publishDateMaxstring<date-time>

Filter posts scheduled on or before this date (ISO 8601 format)

createdAtMinstring<date-time>

Filter posts created on or after this date (ISO 8601 format)

createdAtMaxstring<date-time>

Filter posts created on or before this date (ISO 8601 format)

sortBystring

Field to sort by

default: "createdAt"

Allowed:createdAtpublishAt

sortOrderstring

Sort order

default: "desc"

Allowed:ascdesc

Responses

200

List of posts

postsPost[]

Show properties

Array of Post

idstring<uuid>

urlstring<uri>

titlestring

channelsstring[]

statusPostStatus

Allowed:TentativeToDoInProgressForReviewBlockedFinalizedScheduledPosted

publishDatestring

Scheduled publish date (YYYY-MM-DD) in workspace timezone

publishAtstring<date-time> | null

Scheduled publish datetime UTC. Only set when a specific time is specified.

createdAtstring<date-time>

updatedAtstring<date-time>

archivedAtstring<date-time> | null

When the post was archived. Null if the post is not archived.

labelsobject[]

Labels assigned to this post

Show properties

Array of object

idstring<uuid>

Label ID

namestring

Label name

colorstring

Label text color (hex)

backgroundColorstring

Label background color (hex)

linkedInobject | null

Show properties

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

copystring

assetsAsset[]

Assets attached to the LinkedIn post

Show properties

Array of Asset

idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

xobject | null

X (Twitter) content. Present when the post targets the Twitter channel.

Show properties

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

tweetsobject[]

Show properties

Array of object

copystring

assetsAsset[]

Assets attached to this tweet

Show properties

Array of Asset

idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

instagramInstagramContent | null

Instagram content. Present when the post targets the Instagram channel. The shape depends on the type field.

Show properties

One of:

InstagramFeedContent

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

typestring

Instagram content type

Allowed:Feed

copystring

Caption text

assetsInstagramAsset[]

Show properties

Array of InstagramAsset

idstring<uuid>

namestring

urlstring<uri>

mimetypestring

sizeinteger

widthinteger | null

heightinteger | null

durationnumber | null

tagsInstagramAssetTag[]

Show properties

Array of InstagramAssetTag

usernamestring

Instagram username

xnumber | null

X coordinate (0-1) for images, null for videos

ynumber | null

Y coordinate (0-1) for images, null for videos

collaboratorsstring[]

Instagram usernames invited as collaborators

locationobject | null

Tagged location

Show properties

pageIdstring

Facebook Page ID

namestring

Display name of the location

InstagramReelContent

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

typestring

Instagram content type

Allowed:Reel

copystring

Caption text

assetsInstagramAsset[]

coverPhotoobject | null

Custom cover photo for the Reel

Show properties

idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

shareToFeedboolean

Whether the Reel is also shared to the Feed

trialReelGraduationStrategystring | null

Trial reel graduation strategy, or null if the Reel is not a trial reel. MANUAL requires you to graduate the reel from the Instagram app; SS_PERFORMANCE lets Instagram auto-graduate based on early performance.

Allowed:MANUALSS_PERFORMANCE

collaboratorsstring[]

Instagram usernames invited as collaborators

locationobject | null

Tagged location

Show properties

pageIdstring

Facebook Page ID

namestring

Display name of the location

InstagramStoryContent

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

typestring

Instagram content type

Allowed:Story

assetsInstagramAsset[]

tikTokTikTokContent | null

TikTok content. Present when the post targets the TikTok channel.

Show properties

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

copystring

Caption text

assetsAsset[]

Assets attached to the TikTok post (one video).

Show properties

Array of Asset

idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

privacyLevelTikTokPrivacyLevel

Audience visibility for the TikTok video.

Allowed:PUBLIC_TO_EVERYONEFOLLOWER_OF_CREATORMUTUAL_FOLLOW_FRIENDSSELF_ONLY

isCommentDisabledboolean

isDuetDisabledboolean

isStitchDisabledboolean

isPromotingBusinessboolean

isPaidPartnershipboolean

videoCoverTimestampMsinteger<int32> | null

Timestamp (in milliseconds) of the video frame used as the cover thumbnail. Null when not set.

youTubeShortsYouTubeShortsContent | null

YouTube Shorts content. Present when the post targets the YouTube Shorts channel.

Show properties

profileobject | null

Show properties

idstring<uuid>

Profile ID

namestring | null

Profile name

detailstring | null

Profile detail (vanity name for LinkedIn, @username for X)

titlestring | null

Video title

descriptionstring | null

Video description

assetsAsset[]

Assets attached to the YouTube Shorts post (one video).

Show properties

Array of Asset

idstring<uuid>

Asset ID

namestring

Original filename

urlstring<uri>

URL to access the asset

mimetypestring

MIME type of the file (e.g., image/jpeg, video/mp4)

sizeinteger

File size in bytes

widthinteger | null

Width in pixels for images and videos

heightinteger | null

Height in pixels for images and videos

durationnumber | null

Duration in seconds for videos

privacyStatusYouTubePrivacyStatus

Audience visibility for the YouTube Shorts video.

Allowed:publicprivateunlisted

categoryIdstring | null

notifySubscribersboolean

isEmbeddableboolean

isSelfDeclaredMadeForKidsboolean

nextCursorstring | null

Cursor for the next page of results

hasMoreboolean

Whether there are more results

401

Unauthorized - Missing or invalid API key

codestring

messagestring

429

Too Many Requests - Rate limit exceeded

codestring

messagestring

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

limitqueryMaximum number of posts to return (1-100)cursorqueryCursor for pagination (post ID from the last item of previous page)idsqueryFetch specific posts by IDs. Can be a single UUID or comma-separated list.statusqueryFilter by post statuschannelqueryFilter by channellinkedInProfileIdqueryFilter by LinkedIn profile IDxProfileIdqueryFilter by X/Twitter profile IDinstagramProfileIdqueryFilter by Instagram profile IDtikTokProfileIdqueryFilter by TikTok profile IDyouTubeProfileIdqueryFilter by YouTube channel profile IDlabelIdsqueryFilter by label IDs (posts with any of these labels). Can be a single UUID or comma-separated list.publishDateMinqueryFilter posts scheduled on or after this date (ISO 8601 format)publishDateMaxqueryFilter posts scheduled on or before this date (ISO 8601 format)createdAtMinqueryFilter posts created on or after this date (ISO 8601 format)createdAtMaxqueryFilter posts created on or before this date (ISO 8601 format)sortByqueryField to sort bysortOrderquerySort order

Request

curl -X GET 'https://app.tryordinal.com/api/v1/posts' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch("https://app.tryordinal.com/api/v1/posts", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://app.tryordinal.com/api/v1/posts",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "posts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://app.tryordinal.com/acme/posts/550e8400-e29b-41d4-a716-446655440000",
      "title": "Q4 Product Launch Announcement",
      "channels": [
        "LinkedIn",
        "Twitter"
      ],
      "status": "Scheduled",
      "publishDate": "2026-01-15",
      "publishAt": "2026-01-15T14:00:00.000Z",
      "createdAt": "2026-01-05T10:30:00.000Z",
      "updatedAt": "2026-01-05T11:45:00.000Z",
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440400",
          "name": "Marketing",
          "color": "#9333ea",
          "backgroundColor": "#f3e8ff"
        }
      ],
      "linkedIn": {
        "profile": {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "John Doe",
          "detail": "johndoe"
        },
        "copy": "Excited to announce our new product launch! 🚀",
        "assets": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440010",
            "name": "product-photo.jpg",
            "url": "https://cdn.tryordinal.com/assets/product-photo.jpg",
            "mimetype": "image/jpeg",
            "size": 245678,
            "width": 1920,
            "height": 1080,
            "duration": null
          }
        ]
      },
      "x": {
        "profile": {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "name": "Acme Inc",
          "detail": "@acme_inc"
        },
        "tweets": [
          {
            "copy": "Excited to announce our new product launch! 🚀",
            "assets": []
          }
        ]
      }
    }
  ],
  "nextCursor": "550e8400-e29b-41d4-a716-446655440001",
  "hasMore": true
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or unauthorized API key"
}

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit of 100 requests per 60s exceeded. Quota resets in 45 seconds"
}