> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Social Posts

> List social posts with cursor pagination.

Returns social posts for the API key's organization, sorted by `created_at` descending.

Use this endpoint for dashboards, sync jobs, and agents that need to page through posts. Use `GET /social/post/{post_id}` when you need the freshest status for one specific post.

## Request

```bash theme={null}
curl -X GET "https://api.mosaic.so/social/posts?limit=20" \
  -H "Authorization: Bearer mk_your_api_key"
```

## Query Parameters

| Field                  | Type          | Required | Description                                                                                                                                       |
| ---------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`                | integer       | No       | Maximum posts to return. Defaults to `20`; maximum is `100`.                                                                                      |
| `cursor`               | string        | No       | Cursor returned by the previous response.                                                                                                         |
| `status`               | string        | No       | Filter by post status. Supported values are `scheduled`, `pending_approval`, `processing`, `posted`, `partial_failure`, `failed`, and `rejected`. |
| `platform`             | string        | No       | Filter by platform: `x`, `linkedin`, `instagram`, `facebook`, `tiktok`, or `youtube`.                                                             |
| `social_connection_id` | string (uuid) | No       | Filter to posts that target one connected account.                                                                                                |

## Filtered Request

```bash theme={null}
curl -X GET "https://api.mosaic.so/social/posts?platform=x&social_connection_id=4df2f2b9-4c5f-4b3a-9581-1bcb8b4f7d01&limit=10" \
  -H "Authorization: Bearer mk_your_api_key"
```

## Response

```json theme={null}
{
  "posts": [
    {
      "post_id": "2d8ca860-f8e0-4f3f-9f2c-337ead6ed91e",
      "status": "posted",
      "description": "Launch day recap from the Mosaic team.",
      "thumbnail_url": "https://cdn.yourdomain.com/media/launch-thumbnail.jpg",
      "scheduled_at": "2026-03-10T16:00:00Z",
      "platforms": ["x", "linkedin"],
      "destinations": [
        {
          "social_connection_id": "4df2f2b9-4c5f-4b3a-9581-1bcb8b4f7d01",
          "platform": "x",
          "account_name": "Mosaic",
          "account_username": "mosaic_so",
          "profile_url": "https://x.com/mosaic_so"
        },
        {
          "social_connection_id": "7f9388af-26e8-4e68-a52b-6b9a0ef3a017",
          "platform": "linkedin",
          "account_name": "Mosaic",
          "account_username": "mosaic-so",
          "profile_url": "https://www.linkedin.com/company/mosaic-so"
        }
      ],
      "links": [
        {
          "platform": "x",
          "post_url": "https://x.com/mosaic_so/status/1901625213503277588",
          "social_connection_id": "4df2f2b9-4c5f-4b3a-9581-1bcb8b4f7d01"
        }
      ],
      "results": [
        {
          "social_connection_id": "4df2f2b9-4c5f-4b3a-9581-1bcb8b4f7d01",
          "platform": "x",
          "status": "success",
          "platform_post_id": "1901625213503277588",
          "post_url": "https://x.com/mosaic_so/status/1901625213503277588",
          "message": null
        },
        {
          "social_connection_id": "7f9388af-26e8-4e68-a52b-6b9a0ef3a017",
          "platform": "linkedin",
          "status": "success",
          "platform_post_id": "7351291821454032896",
          "post_url": "https://www.linkedin.com/company/mosaic-so/posts/...",
          "message": null
        }
      ],
      "destination_results": [
        {
          "social_connection_id": "4df2f2b9-4c5f-4b3a-9581-1bcb8b4f7d01",
          "platform": "x",
          "status": "success",
          "platform_post_id": "1901625213503277588",
          "post_url": "https://x.com/mosaic_so/status/1901625213503277588",
          "message": null
        },
        {
          "social_connection_id": "7f9388af-26e8-4e68-a52b-6b9a0ef3a017",
          "platform": "linkedin",
          "status": "success",
          "platform_post_id": "7351291821454032896",
          "post_url": "https://www.linkedin.com/company/mosaic-so/posts/...",
          "message": null
        }
      ],
      "error": null,
      "created_at": "2026-03-10T16:00:00.000Z",
      "updated_at": "2026-03-10T16:00:09.000Z"
    },
    {
      "post_id": "4ce8de72-7d67-48dc-bd11-0362d5cebb51",
      "status": "scheduled",
      "description": "Motion product update",
      "thumbnail_url": "https://cdn.yourdomain.com/media/motion-launch.jpg",
      "scheduled_at": "2026-03-11T18:00:00Z",
      "platforms": ["x", "linkedin"],
      "destinations": [
        {
          "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628",
          "platform": "x",
          "account_name": "Motion",
          "account_username": "motion_so",
          "profile_url": "https://x.com/motion_so"
        },
        {
          "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d",
          "platform": "linkedin",
          "account_name": "Motion",
          "account_username": "motion-so",
          "profile_url": "https://www.linkedin.com/company/motion-so/"
        }
      ],
      "links": [],
      "results": [
        {
          "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628",
          "platform": "x",
          "status": "scheduled",
          "platform_post_id": null,
          "post_url": null,
          "message": null
        },
        {
          "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d",
          "platform": "linkedin",
          "status": "scheduled",
          "platform_post_id": null,
          "post_url": null,
          "message": null
        }
      ],
      "destination_results": [
        {
          "social_connection_id": "62c07212-eeb5-40e2-9902-e478027b8628",
          "platform": "x",
          "status": "scheduled",
          "platform_post_id": null,
          "post_url": null,
          "message": null
        },
        {
          "social_connection_id": "8b59f2d7-53fa-4f47-9850-cb4b78b19a8d",
          "platform": "linkedin",
          "status": "scheduled",
          "platform_post_id": null,
          "post_url": null,
          "message": null
        }
      ],
      "error": null,
      "created_at": "2026-03-10T15:30:00.000Z",
      "updated_at": "2026-03-10T15:30:01.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "returned": 2,
    "has_more": true,
    "next_cursor": "eyJ2ZXJzaW9uIjoidjEiLCJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xMFQxNTozMDowMC4wMDBaIiwiaWQiOiI0Y2U4ZGU3Mi03ZDY3LTQ4ZGMtYmQxMS0wMzYyZDVjZWJiNTEifQ",
    "sort": "created_at_desc"
  }
}
```

## Pagination

* Results are sorted by `created_at` descending.
* `next_cursor` is opaque. Pass it back as `cursor` to get the next page.
* `has_more` is `false` and `next_cursor` is `null` when there are no more posts.
* List responses do not refresh destination status from the social platforms. Use `GET /social/post/{post_id}` for a fresh read of one post.