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

# Get Posts

> Retrieve posts with optional filters

## Endpoint

```
POST https://api.ugc.inc/post
```

## Overview

Retrieve a list of posts (videos and slideshows) with optional filtering by account IDs and date range. Use this endpoint to monitor and track all posts across your accounts.

Supports keyset pagination via `limit`/`cursor` — pass `limit` to page through results
newest-first, using each response's `nextCursor` to fetch the next page.

## Request Body

<ParamField body="accountIds" type="string[]">
  Array of account IDs to filter posts by. Omit to get all posts.
</ParamField>

<ParamField body="postIds" type="string[]">
  Array of specific post IDs to retrieve. Use this to fetch specific posts by their IDs.
</ParamField>

<ParamField body="startDate" type="string">
  Start date in ISO 8601 format (e.g., `2024-01-01T00:00:00Z`)
</ParamField>

<ParamField body="endDate" type="string">
  End date in ISO 8601 format (e.g., `2024-12-31T23:59:59Z`)
</ParamField>

<ParamField body="limit" type="number">
  Max rows to return. Omit to fetch all matching posts (no pagination).
</ParamField>

<ParamField body="cursor" type="string">
  Opaque cursor from a previous response's `nextCursor`, to fetch the next page. Results are
  ordered newest-first.
</ParamField>

## Response

<ResponseField name="data" type="Post[]">
  Array of post objects

  <Expandable title="Post properties">
    <ResponseField name="id" type="string">
      Unique post identifier
    </ResponseField>

    <ResponseField name="account_id" type="string">
      ID of the account that created this post
    </ResponseField>

    <ResponseField name="type" type="'video' | 'slideshow'">
      Type of post content
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `scheduled`, `pending`, `complete`, or `failed`
    </ResponseField>

    <ResponseField name="social_id" type="string | null">
      Platform-specific post ID (TikTok video ID or Instagram reel code, available after posting)
    </ResponseField>

    <ResponseField name="caption" type="string | null">
      Post caption/description text (max 4000 characters)
    </ResponseField>

    <ResponseField name="tag" type="string | null">
      Custom tag stored on the post (set via `post_tag` on create/update endpoints)
    </ResponseField>

    <ResponseField name="media_urls" type="string[] | null">
      Array of URLs to video/image files used in the post
    </ResponseField>

    <ResponseField name="music_post_id" type="string | null">
      Legacy field for music/audio ID (deprecated in favor of social\_audio\_id)
    </ResponseField>

    <ResponseField name="scheduled_at" type="string | null">
      When the post is scheduled to be published (ISO 8601 format)
    </ResponseField>

    <ResponseField name="postUrl" type="string | undefined">
      Direct URL to the post on the social media platform. Only available when status is `complete` and the post has been published.

      * **TikTok**: `https://www.tiktok.com/@username/video/{social_id}`
      * **Instagram**: `https://www.instagram.com/p/{social_id}/`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextCursor" type="string | null">
  Present when `limit` was passed. Pass back as `cursor` to fetch the next page; `null` means
  there are no more pages.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.ugc.inc/post \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "accountIds": ["acc_123456"],
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z"
    }'
  ```

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

  response = requests.post(
      'https://api.ugc.inc/post',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'accountIds': ['acc_123456'],
          'startDate': '2024-01-01T00:00:00Z',
          'endDate': '2024-12-31T23:59:59Z'
      }
  )

  data = response.json()

  if data['ok']:
      for post in data['data']:
          print(f"Post {post['id']} ({post['type']}): {post['status']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.ugc.inc/post', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      accountIds: ['acc_123456'],
      startDate: '2024-01-01T00:00:00Z',
      endDate: '2024-12-31T23:59:59Z'
    })
  });

  const data = await response.json();

  if (data.ok) {
    data.data.forEach(post => {
      console.log(`Post ${post.id} (${post.type}): ${post.status}`);
    });
  }
  ```

  ```typescript React theme={null}
  import { UGCClient } from 'ugcinc';

  const client = new UGCClient({
    apiKey: 'YOUR_API_KEY'
  });

  // Get posts by account IDs and date range
  const response = await client.posts.getPosts({
    accountIds: ['acc_123456'],
    startDate: '2024-01-01T00:00:00Z',
    endDate: '2024-12-31T23:59:59Z'
  });

  // Or get specific posts by ID
  const specificPosts = await client.posts.getPosts({
    postIds: ['post_abc123', 'post_def456']
  });

  if (response.ok) {
    response.data.forEach(post => {
      console.log(`Post ${post.id}:`);
      console.log(`  Type: ${post.type}`);
      console.log(`  Status: ${post.status}`);
      console.log(`  Caption: ${post.caption}`);
      
      // postUrl is available for completed posts
      if (post.postUrl) {
        console.log(`  URL: ${post.postUrl}`);
      }
    });
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Success",
    "data": [
      {
        "id": "post_abc123",
        "account_id": "acc_123456",
        "type": "video",
        "status": "complete",
        "social_id": "7234567890123456789",
        "caption": "Check out this awesome video! 🎥 #viral",
        "media_urls": [
          "https://storage.example.com/video1.mp4"
        ],
        "music_post_id": "audio_xyz789",
        "scheduled_at": "2024-01-15T14:30:00Z",
        "postUrl": "https://www.tiktok.com/@username/video/7234567890123456789"
      },
      {
        "id": "post_def456",
        "account_id": "acc_123456",
        "type": "slideshow",
        "status": "scheduled",
        "social_id": null,
        "caption": "Amazing photos from today 📸",
        "media_urls": [
          "https://storage.example.com/img1.jpg",
          "https://storage.example.com/img2.jpg",
          "https://storage.example.com/img3.jpg"
        ],
        "music_post_id": "audio_abc123",
        "scheduled_at": "2024-01-20T10:00:00Z"
      }
    ],
    "nextCursor": null
  }
  ```
</ResponseExample>