---
title: "List posts"
method: GET
path: "/v1/posts"
tags: ["Posts"]
---

# List posts

`GET /v1/posts`

## Request

- Base URL: `https://api.outstand.so`
- URL: `https://api.outstand.so/v1/posts`
- Auth: none declared

Get a paginated list of posts for the current organization with optional filters. Results include post content, containers, scheduling status, and publishing state. Each returned post includes its unique ID, which can be used with GET /v1/posts/:id for full details or DELETE /v1/posts/:id to cancel a scheduled post.

**Filtering:**
- `tenant_id` - Filter by tenant ID for multi-tenant applications (exact match). Posts carry no tenant of their own, so a post matches when at least one of its target social accounts has that tenant ID. `tenantId` is accepted as an alias for parity with GET /v1/social-accounts.
- `social_account_id` - Filter by social account ID (posts targeting that account). Accepts the encoded ID returned by the API, or a raw numeric ID.
- `created_after` / `created_before` - Creation timestamp range (ISO 8601)
- `scheduled_after` / `scheduled_before` - Scheduled timestamp range (ISO 8601)
- All filters combine with AND.

Note that filters select *posts*: a matching post is returned with its full `socialAccounts` array, so a post fanned out across several tenants will list all of its accounts. When `tenant_id` and `social_account_id` are combined they must be satisfied by the same account, so pairing a tenant with an account outside it returns no results rather than matching through a sibling account.

**Pagination:** use `limit` and `offset`. `pagination.total` is the total number of posts matching the filters across all pages; `pagination.count` is the number of posts in the current page.

## Query parameters

- `social_account_id` string
- `tenant_id` string
- `tenantId` string
- `created_after` string, date-time
- `created_before` string, date-time
- `scheduled_after` string, date-time
- `scheduled_before` string, date-time
- `limit` string
- `offset` string

## Response `200`

Posts retrieved successfully

- object
  - `success` boolean, required
  - `posts` object[], required: Array of posts (kept for backward compatibility)
    - `id` string, required
    - `orgId` string, required
    - `publishedAt` string, date-time, nullable, required
    - `scheduledAt` string, date-time, nullable, required
    - `isDraft` boolean, required
    - `createdAt` string, date-time, required
    - `socialAccounts` object[], required
      - `id` string, required: Unique identifier for the social account
      - `nickname` string, required: User-defined nickname for this social account
      - `network` string, required: Social network identifier (e.g., 'facebook', 'x', 'instagram', 'linkedin', 'threads', 'youtube', 'tiktok')
      - `username` string, required: Username or handle on the social network
      - `status` 'pending' | 'published' | 'failed' | 'deleted', required: Publishing status for this account. 'pending': awaiting publish (post created or scheduled), 'published': successfully published to this account, 'failed': publishing failed (check error field), 'deleted': post was deleted from the social network platform. Note: A post can partially succeed - some accounts may publish while others fail.
      - `error` string, nullable, required: Error message if publishing failed. Contains the platform-specific error message. Common errors include: expired access tokens, rate limits, invalid media format, content policy violations. Null if status is not 'failed'.
      - `platformPostId` string, nullable, required: The platform-specific post ID after successful publish. Use this for analytics, fetching comments, or deep-linking to the post on the platform. Null if not yet published or if publishing failed.
      - `platformPostUrl` string, nullable, required: The public URL of the post on the social network. Currently populated for Instagram only; null for other networks or for posts created before this feature.
      - `publishedAt` string, date-time, nullable, required: ISO 8601 timestamp when the post was successfully published to this account. Null if pending or failed. Each account has its own publishedAt since they are processed sequentially.
    - `containers` object[], required
      - `id` string, required
      - `content` string, required
      - `media` object[], required
        - `url` string, required
        - `filename` string, required
  - `data` object[]: Array of posts (for UI package compatibility)
    - `id` string, required
    - `orgId` string, required
    - `publishedAt` string, date-time, nullable, required
    - `scheduledAt` string, date-time, nullable, required
    - `isDraft` boolean, required
    - `createdAt` string, date-time, required
    - `socialAccounts` object[], required
      - `id` string, required: Unique identifier for the social account
      - `nickname` string, required: User-defined nickname for this social account
      - `network` string, required: Social network identifier (e.g., 'facebook', 'x', 'instagram', 'linkedin', 'threads', 'youtube', 'tiktok')
      - `username` string, required: Username or handle on the social network
      - `status` 'pending' | 'published' | 'failed' | 'deleted', required: Publishing status for this account. 'pending': awaiting publish (post created or scheduled), 'published': successfully published to this account, 'failed': publishing failed (check error field), 'deleted': post was deleted from the social network platform. Note: A post can partially succeed - some accounts may publish while others fail.
      - `error` string, nullable, required: Error message if publishing failed. Contains the platform-specific error message. Common errors include: expired access tokens, rate limits, invalid media format, content policy violations. Null if status is not 'failed'.
      - `platformPostId` string, nullable, required: The platform-specific post ID after successful publish. Use this for analytics, fetching comments, or deep-linking to the post on the platform. Null if not yet published or if publishing failed.
      - `platformPostUrl` string, nullable, required: The public URL of the post on the social network. Currently populated for Instagram only; null for other networks or for posts created before this feature.
      - `publishedAt` string, date-time, nullable, required: ISO 8601 timestamp when the post was successfully published to this account. Null if pending or failed. Each account has its own publishedAt since they are processed sequentially.
    - `containers` object[], required
      - `id` string, required
      - `content` string, required
      - `media` object[], required
        - `url` string, required
        - `filename` string, required
  - `pagination` object, required
    - `limit` number, required
    - `offset` number, required
    - `total` number, required: Total number of posts matching the filters, across all pages
    - `count` number, required: Number of posts in this page

## Other responses

- `400`: Invalid query parameters
- `500`: Internal server error

---

[API](https://skmtc.dev/outstand/apis/outstand-posts-v1.md) · [All operations](https://skmtc.dev/outstand/apis/outstand-posts-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/outstand/apis/outstand-posts-v1/revisions/9cf3d8976019?raw)