Skip to main content

​
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

​
accountIds
string[]
Array of account IDs to filter posts by. Omit to get all posts.
​
postIds
string[]
Array of specific post IDs to retrieve. Use this to fetch specific posts by their IDs.
​
startDate
string
Start date in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)
​
endDate
string
End date in ISO 8601 format (e.g., 2024-12-31T23:59:59Z)
​
limit
number
Max rows to return. Omit to fetch all matching posts (no pagination).
​
cursor
string
Opaque cursor from a previous response’s nextCursor, to fetch the next page. Results are ordered newest-first.

​
Response

​
data
Post[]
Array of post objects
​
nextCursor
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
}