Get Posts

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"
  }'

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']}")

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}`);
  });
}

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}`);
    }
  });
}

{
  "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
}

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

string[]

Array of account IDs to filter posts by. Omit to get all posts.

string[]

Array of specific post IDs to retrieve. Use this to fetch specific posts by their IDs.

string

Start date in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)

string

End date in ISO 8601 format (e.g., 2024-12-31T23:59:59Z)

number

Max rows to return. Omit to fetch all matching posts (no pagination).

string

Opaque cursor from a previous response’s nextCursor, to fetch the next page. Results are ordered newest-first.

Response

Post[]

Array of post objects

Show Post properties

string

Unique post identifier

string

ID of the account that created this post

'video' | 'slideshow'

Type of post content

string

Current status: scheduled, pending, complete, or failed

Platform-specific post ID (TikTok video ID or Instagram reel code, available after posting)

string | null

Post caption/description text (max 4000 characters)

string | null

Custom tag stored on the post (set via post_tag on create/update endpoints)

string[] | null

Array of URLs to video/image files used in the post

string | null

Legacy field for music/audio ID (deprecated in favor of social_audio_id)

string | null

When the post is scheduled to be published (ISO 8601 format)

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}/

string | null

Present when limit was passed. Pass back as cursor to fetch the next page; null means there are no more pages.

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"
  }'

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']}")

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}`);
  });
}

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}`);
    }
  });
}

{
  "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
}

Getting Started

Data Structures

Posts

Comments

Accounts

Statistics

Tasks

Organization

Media

Billing

Automations

Endpoint

Overview

Request Body

Response

​Endpoint

​Overview

​Request Body

​Response

Endpoint

Overview

Request Body

Response