Get Started

Posts

API endpoint for retrieving workspace posts with optional filtering, sorting, and pagination. Requires authentication and posts:view permission.

GET/posts

Headers

x-api-keystringrequired

Your Track My Posts API key

Query Parameters

workspaceSlugstringrequired

Workspace slug identifier

Example: my-workspace

querystring

Search query to filter posts by caption, mentions, or hashtags

Example: fitness

sincestring

Start date filter for postedAt (YYYY-MM-DD or ISO 8601 format)

Example: 2024-01-01

untilstring

End date filter for postedAt (YYYY-MM-DD or ISO 8601 format)

Example: 2024-12-31

platformsarray

Filter by platforms (comma-separated or array)

Example: tiktokinstagram

typesarray

Filter by post types (comma-separated or array). Alias: postTypes

Example: videophoto

postTypesarray

Filter by post types (comma-separated or array). Alias for types

Example: video

slugsarray

Filter by post slugs (comma-separated or array)

Example: 123456

creatorarray

Filter by creator slugs (comma-separated or array). Alias: creatorSlugs

Example: 123456

creatorSlugsarray

Filter by creator slugs (comma-separated or array). Alias for creator

Example: 123

accountarray

Filter by account slugs (comma-separated or array). Alias: accountSlugs

Example: 123456

accountSlugsarray

Filter by account slugs (comma-separated or array). Alias for account

Example: 123

pageinteger

Page number (1-indexed)

Example: 1

limitinteger

Number of items per page

Example: 20

sortBystring

Field to sort by

Example: postedAt

sortOrderstring

Sort order

Example: desc

isTrackedstring

Filter by tracked status. true = only tracked posts, false = only untracked posts, null or omitted = all posts

Example: true

isExportboolean

Enable export mode (removes pagination limits)

ignoreLimitboolean

Ignore the 5000 post limit in the base query

ignorePostedAtFilterboolean

Do not filter posts by postedAt range, but still use since/until for stats boundaries

Responses

200Successful response with posts data
400Bad request - validation error
401Unauthorized - authentication required
403Forbidden - insufficient permissions
404Not found - workspace not found
500Internal server error
curl "https://api.trackmyposts.com/posts?workspaceSlug=my-workspace&query=fitness&since=2024-01-01&until=2024-12-31&platforms=tiktok%2Cinstagram&types=video%2Cphoto&postTypes=video&slugs=123%2C456&creator=123%2C456&creatorSlugs=123&account=123%2C456&accountSlugs=123&page=1&limit=20&sortBy=postedAt&sortOrder=desc&isTracked=true&isExport=false&ignoreLimit=false&ignorePostedAtFilter=false" \
  -H "x-api-key: YOUR_API_KEY"
{
  "items": [
    {
      "id": "post-123",
      "workspaceId": "workspace-123",
      "accountId": "account-123",
      "slug": 123,
      "platformPostId": "tiktok_123456",
      "platform": "tiktok",
      "type": "video",
      "postUrl": "https://tiktok.com/@user/video/123456",
      "thumbnailUrl": "https://example.com/thumb.jpg",
      "videoUrl": "https://example.com/video.mp4",
      "caption": "Check out this amazing video! #fitness",
      "mentions": [
        "@user1"
      ],
      "hashtags": [
        "fitness",
        "workout"
      ],
      "isPaidPartnership": false,
      "postedAt": "2024-01-15T10:30:00.000Z",
      "durationMs": 30000,
      "soundTitle": "Original Sound",
      "soundAuthor": "creator",
      "isOriginalSound": true,
      "isTracked": true,
      "createdAt": "2024-01-15T10:30:05.000Z",
      "updatedAt": "2024-01-15T10:30:05.000Z",
      "views": 100000,
      "likes": 5000,
      "comments": 200,
      "shares": 150,
      "saves": 300,
      "engagementRate": 5.5,
      "revenueMin": 100,
      "revenueMax": 150,
      "rpmMin": 1,
      "rpmMax": 1.5,
      "cost": 50,
      "cpm": 0.5,
      "profitMin": 50,
      "profitMax": 100,
      "costSummary": null,
      "stats": [],
      "account": {
        "id": "account-123",
        "workspaceId": "workspace-123",
        "creatorId": "creator-123",
        "accountUrl": "https://tiktok.com/@user",
        "platform": "tiktok",
        "username": "@user",
        "status": "active"
      },
      "creator": {
        "id": "creator-123",
        "workspaceId": "workspace-123",
        "slug": 123,
        "name": "John Doe"
      },
      "trackingStartedAt": "2024-01-15T10:30:05.000Z",
      "lastStatsAt": "2024-01-15T12:00:00.000Z",
      "limitedData": false
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 150,
  "totalPages": 8,
  "hasNext": true,
  "hasPrev": false
}

Data Structures

View all 3 data structuresPosts

Explore all data structures used in this API endpoint