> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryordinal.com/llms.txt > Use this file to discover all available pages before exploring further. # List posts > List all posts in the workspace with pagination and filtering. Archived posts are excluded from results. ## OpenAPI ````yaml /api/openapi.json get /posts openapi: 3.1.0 info: title: Ordinal API version: 1.0.0 description: API to create and manage Ordinal workspaces, posts, profiles, and analytics servers: - url: https://app.tryordinal.com/api/v1 description: Production server security: - bearerAuth: [] tags: - name: Analytics description: Social media analytics data - name: Approvals description: Post approval workflows - name: Comments description: >- Post comments for team collaboration. Supports @mentions using the format @[Display Name](userId). - name: Engagements description: Auto-engagements for posts (likes, comments, reposts) - name: Invites description: Workspace invitations for adding new users - name: Labels description: Labels for organizing posts - name: Instagram description: Instagram utilities for location search and tagging - name: LinkedIn description: LinkedIn utilities for profile lookups, tagging, and mentions - name: Posts description: Create and manage posts - name: Profiles description: List connected social profiles - name: Slack Boosts description: >- List connected Slack channels (webhooks), then create and manage slack boosts so teams get notified in Slack when posts publish. Requires Slack connected with marketing boost channels. - name: Subscribers description: Post subscribers for notifications - name: File Uploads description: >- Upload files from URLs for use in posts. Supports images (JPEG, PNG, GIF, WebP) up to 10 MB and videos (MP4, MOV) up to 350 MB. - name: Ideas description: >- Create and manage content ideas. Ideas are draft posts without scheduled dates that can be converted to calendar posts. - name: Inline Comments description: >- Text-anchored comments on specific post content. Read-only API for retrieving inline comments across channels. - name: Users description: Workspace users - name: Webhooks description: >- Create, list, get, update, and delete webhooks to receive real-time event notifications - name: Workspaces description: Workspace information paths: /posts: get: tags: - Posts summary: List posts description: >- List all posts in the workspace with pagination and filtering. Archived posts are excluded from results. operationId: posts-list parameters: - name: limit in: query description: Maximum number of posts to return (1-100) schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query description: Cursor for pagination (post ID from the last item of previous page) schema: type: string format: uuid - name: ids in: query description: >- Fetch specific posts by IDs. Can be a single UUID or comma-separated list. schema: oneOf: - type: string format: uuid - type: array items: type: string format: uuid - name: status in: query description: Filter by post status schema: $ref: '#/components/schemas/PostStatus' - name: channel in: query description: Filter by channel schema: type: string enum: - LinkedIn - Twitter - Instagram - TikTok - YouTubeShorts - name: linkedInProfileId in: query description: Filter by LinkedIn profile ID schema: type: string format: uuid - name: xProfileId in: query description: Filter by X/Twitter profile ID schema: type: string format: uuid - name: instagramProfileId in: query description: Filter by Instagram profile ID schema: type: string format: uuid - name: tikTokProfileId in: query description: Filter by TikTok profile ID schema: type: string format: uuid - name: youTubeProfileId in: query description: Filter by YouTube channel profile ID schema: type: string format: uuid - name: labelIds in: query description: >- Filter by label IDs (posts with any of these labels). Can be a single UUID or comma-separated list. schema: oneOf: - type: string format: uuid - type: array items: type: string format: uuid - name: publishDateMin in: query description: Filter posts scheduled on or after this date (ISO 8601 format) schema: type: string format: date-time - name: publishDateMax in: query description: Filter posts scheduled on or before this date (ISO 8601 format) schema: type: string format: date-time - name: createdAtMin in: query description: Filter posts created on or after this date (ISO 8601 format) schema: type: string format: date-time - name: createdAtMax in: query description: Filter posts created on or before this date (ISO 8601 format) schema: type: string format: date-time - name: sortBy in: query description: Field to sort by schema: type: string enum: - createdAt - publishAt default: createdAt - name: sortOrder in: query description: Sort order schema: type: string enum: - asc - desc default: desc responses: '200': description: List of posts content: application/json: schema: type: object properties: posts: type: array items: $ref: '#/components/schemas/Post' nextCursor: type: string nullable: true description: Cursor for the next page of results hasMore: type: boolean description: Whether there are more results example: 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 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' components: schemas: PostStatus: type: string enum: - Tentative - ToDo - InProgress - ForReview - Blocked - Finalized - Scheduled - Posted Post: type: object properties: id: type: string format: uuid url: type: string format: uri title: type: string channels: type: array items: type: string status: $ref: '#/components/schemas/PostStatus' publishDate: type: string description: Scheduled publish date (YYYY-MM-DD) in workspace timezone publishAt: type: string format: date-time nullable: true description: >- Scheduled publish datetime UTC. Only set when a specific time is specified. createdAt: type: string format: date-time updatedAt: type: string format: date-time archivedAt: type: string format: date-time nullable: true description: When the post was archived. Null if the post is not archived. labels: type: array description: Labels assigned to this post items: type: object properties: id: type: string format: uuid description: Label ID name: type: string description: Label name color: type: string description: Label text color (hex) backgroundColor: type: string description: Label background color (hex) linkedIn: type: object nullable: true properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true copy: type: string assets: type: array description: Assets attached to the LinkedIn post items: $ref: '#/components/schemas/Asset' x: type: object nullable: true description: >- X (Twitter) content. Present when the post targets the Twitter channel. properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true tweets: type: array items: type: object properties: copy: type: string assets: type: array description: Assets attached to this tweet items: $ref: '#/components/schemas/Asset' instagram: $ref: '#/components/schemas/InstagramContent' tikTok: $ref: '#/components/schemas/TikTokContent' youTubeShorts: $ref: '#/components/schemas/YouTubeShortsContent' ChannelProfile: type: object description: Profile information for a channel (LinkedIn, X, or Instagram) properties: id: type: string format: uuid description: Profile ID name: type: string nullable: true description: Profile name detail: type: string nullable: true description: Profile detail (vanity name for LinkedIn, @username for X) Asset: type: object description: Asset metadata for files attached to posts properties: id: type: string format: uuid description: Asset ID name: type: string description: Original filename url: type: string format: uri description: URL to access the asset mimetype: type: string description: MIME type of the file (e.g., image/jpeg, video/mp4) size: type: integer description: File size in bytes width: type: integer nullable: true description: Width in pixels for images and videos height: type: integer nullable: true description: Height in pixels for images and videos duration: type: number nullable: true description: Duration in seconds for videos InstagramContent: nullable: true description: >- Instagram content. Present when the post targets the Instagram channel. The shape depends on the `type` field. oneOf: - $ref: '#/components/schemas/InstagramFeedContent' - $ref: '#/components/schemas/InstagramReelContent' - $ref: '#/components/schemas/InstagramStoryContent' discriminator: propertyName: type mapping: Feed: $ref: '#/components/schemas/InstagramFeedContent' Reel: $ref: '#/components/schemas/InstagramReelContent' Story: $ref: '#/components/schemas/InstagramStoryContent' TikTokContent: type: object nullable: true description: TikTok content. Present when the post targets the TikTok channel. properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true copy: type: string description: Caption text assets: type: array description: Assets attached to the TikTok post (one video). items: $ref: '#/components/schemas/Asset' privacyLevel: $ref: '#/components/schemas/TikTokPrivacyLevel' isCommentDisabled: type: boolean isDuetDisabled: type: boolean isStitchDisabled: type: boolean isPromotingBusiness: type: boolean isPaidPartnership: type: boolean videoCoverTimestampMs: type: integer format: int32 nullable: true description: >- Timestamp (in milliseconds) of the video frame used as the cover thumbnail. Null when not set. YouTubeShortsContent: type: object nullable: true description: >- YouTube Shorts content. Present when the post targets the YouTube Shorts channel. properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true title: type: string nullable: true description: Video title description: type: string nullable: true description: Video description assets: type: array description: Assets attached to the YouTube Shorts post (one video). items: $ref: '#/components/schemas/Asset' privacyStatus: $ref: '#/components/schemas/YouTubePrivacyStatus' categoryId: type: string nullable: true notifySubscribers: type: boolean isEmbeddable: type: boolean isSelfDeclaredMadeForKids: type: boolean Error: type: object properties: code: type: string message: type: string InstagramFeedContent: type: object description: Instagram Feed content in responses properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true type: type: string enum: - Feed description: Instagram content type copy: type: string description: Caption text assets: type: array items: $ref: '#/components/schemas/InstagramAsset' collaborators: type: array items: type: string description: Instagram usernames invited as collaborators location: allOf: - $ref: '#/components/schemas/InstagramLocation' nullable: true description: Tagged location InstagramReelContent: type: object description: Instagram Reel content in responses properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true type: type: string enum: - Reel description: Instagram content type copy: type: string description: Caption text assets: type: array items: $ref: '#/components/schemas/InstagramAsset' coverPhoto: allOf: - $ref: '#/components/schemas/Asset' nullable: true description: Custom cover photo for the Reel shareToFeed: type: boolean description: Whether the Reel is also shared to the Feed collaborators: type: array items: type: string description: Instagram usernames invited as collaborators location: allOf: - $ref: '#/components/schemas/InstagramLocation' nullable: true description: Tagged location InstagramStoryContent: type: object description: Instagram Story content in responses properties: profile: allOf: - $ref: '#/components/schemas/ChannelProfile' nullable: true type: type: string enum: - Story description: Instagram content type assets: type: array items: $ref: '#/components/schemas/InstagramAsset' TikTokPrivacyLevel: type: string description: Audience visibility for the TikTok video. enum: - PUBLIC_TO_EVERYONE - FOLLOWER_OF_CREATOR - MUTUAL_FOLLOW_FRIENDS - SELF_ONLY YouTubePrivacyStatus: type: string description: Audience visibility for the YouTube Shorts video. enum: - public - private - unlisted InstagramAsset: type: object description: An asset attached to an Instagram post with user tags properties: id: type: string format: uuid name: type: string url: type: string format: uri mimetype: type: string size: type: integer width: type: integer nullable: true height: type: integer nullable: true duration: type: number nullable: true tags: type: array items: $ref: '#/components/schemas/InstagramAssetTag' InstagramLocation: type: object description: A location tagged on an Instagram post properties: pageId: type: string description: Facebook Page ID name: type: string description: Display name of the location InstagramAssetTag: type: object description: A user tag on an Instagram asset in responses properties: username: type: string description: Instagram username x: type: number nullable: true description: X coordinate (0-1) for images, null for videos 'y': type: number nullable: true description: Y coordinate (0-1) for images, null for videos responses: Unauthorized: description: Unauthorized - Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: code: UNAUTHORIZED message: Invalid or unauthorized API key RateLimited: description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: code: TOO_MANY_REQUESTS message: >- Rate limit of 100 requests per 60s exceeded. Quota resets in 45 seconds securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key authentication. Generate an API key from your workspace settings. ````