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

# List Posts

> List published social posts for a company, with rolled-up analytics

### Endpoint

```http theme={null}
GET https://api.joinoverlap.com/posts?companyId={companyId}
```

Lists posts that Overlap has published to social platforms for your company, newest first, including each post's rolled-up analytics counters. Use it to discover `postId`s for [`GET /post-analytics`](/api-reference/post-analytics), or to find every post published from a specific clip via the `clipId` filter.

### Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

| Parameter               | Required | Description                                                                                                                                                                                                                                   |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`             | Yes      | Your Overlap company or organization identifier.                                                                                                                                                                                              |
| `clipId`                | No       | Return only the posts published from this clip (the clip id from `GET /workflow-results/{triggerId}`). Returns all matches in one response — `sortBy` and `cursor` are ignored on this path.                                                  |
| `platform`              | No       | Filter by platform (`youtube`, `tiktok`, `instagram`, `twitter`, `linkedin`, `facebook`, `threads`, `snapchat`, `bluesky`). Applied per page, so a filtered page may contain fewer than `limit` items — keep paging until `cursor` is `null`. |
| `sortBy`                | No       | `date` (default), `views`, `likes`, or `comments`. Metric sorts order by the post's current rollup, descending.                                                                                                                               |
| `startDate` / `endDate` | No       | ISO-8601 date or datetime bounds on the post's publish time. Only valid with `sortBy=date`.                                                                                                                                                   |
| `limit`                 | No       | Page size, 1–100. Defaults to `25`.                                                                                                                                                                                                           |
| `cursor`                | No       | Pagination cursor from the previous response.                                                                                                                                                                                                 |

<Info>
  The same listing is also available at `GET /companies/{companyId}/posts`.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.joinoverlap.com/posts?companyId=YOUR_COMPANY_ID&sortBy=views&limit=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.joinoverlap.com/posts?companyId=YOUR_COMPANY_ID&sortBy=views&limit=25',
    { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
  );
  const { posts, cursor } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.joinoverlap.com/posts",
      params={"companyId": "YOUR_COMPANY_ID", "sortBy": "views", "limit": 25},
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  posts = response.json()["posts"]
  ```
</RequestExample>

## Response

Returns an array of [`Post` objects](/api-reference/analytics-model#post-object) and a pagination cursor. `cursor` is `null` when there are no more pages; otherwise pass it back as the `cursor` query parameter.

```json theme={null}
{
  "posts": [
    {
      "id": "uV9LKKuVU2IiRcwv7UvY",
      "platform": "youtube",
      "text": "Top agent Jarred Arfa and promoter Danny Hayes say fans finally figured out the game...",
      "postUrl": "https://youtu.be/3j6-UUMa6WE",
      "nativeId": "3j6-UUMa6WE",
      "clipId": "6dd94ba0-908c-4489-897f-4bc02fe96650",
      "status": "success",
      "mediaUrl": "https://.../exported-6dd94ba0.mp4",
      "thumbnailUrl": "https://.../thumb.jpg",
      "createdAt": "2026-07-10T19:31:30+00:00",
      "analytics": { "views": 969, "likes": 9, "comments": 0, "shares": 0 },
      "engagementScore": 27.69,
      "growthRate": 9.1,
      "lastAnalyticsUpdate": "2026-07-10T23:10:31+00:00"
    }
  ],
  "cursor": "uV9LKKuVU2IiRcwv7UvY"
}
```

<CardGroup cols={2}>
  <Card title="Post Analytics" icon="chart-line" href="/api-reference/post-analytics">
    All current analytics for a single post.
  </Card>

  <Card title="Analytics Model" icon="table" href="/api-reference/analytics-model">
    Field-by-field response reference.
  </Card>
</CardGroup>