Response Format

All API responses follow a consistent JSON structure.

Response Structure

All responses include a success boolean and either a data or error object.

Successful Response

{
  "success": true,
  "data": {
    // Response data here
  }
}
    

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}
    

Post Object Structure

Each post in the response contains the following fields:

{
  "id": 12345,
  "platform": "tiktok",
  "platform_post_id": "7234567890123456789",
  "content": "Check out this new dance! #fyp #dance",
  "post_url": "https://www.tiktok.com/@user/video/7234567890123456789",
  "published_at": "2024-01-15T14:30:00Z",
  "media": {
    "type": "video",
    "urls": [
      "https://example.com/video.mp4",
      "https://example.com/thumbnail.jpg"
    ]
  },
  "engagement": {
    "likes": 1500000,
    "comments": 25000,
    "shares": 50000,
    "views": 10000000,
    "total": 1575000
  },
  "author": {
    "username": "charlidamelio",
    "display_name": "Charli D'Amelio",
    "profile_url": "https://www.tiktok.com/@charlidamelio",
    "avatar_url": "https://example.com/avatar.jpg"
  },
  "hashtags": ["fyp", "dance"],
  "mentions": ["username1", "username2"],
  "scraped_at": "2024-01-15T15:00:00Z"
}
    

Field Descriptions

Field	Type	Description
`id`	integer	Internal database ID
`platform`	string	Source platform: tiktok, instagram, twitter, snapchat, linkedin
`platform_post_id`	string	Original post ID from the platform
`content`	string\|null	Post caption/text content
`post_url`	string	Direct URL to the original post
`published_at`	string\|null	ISO 8601 timestamp of publication
`media.type`	string\|null	Media type: image, video, carousel, reel, story, text
`media.urls`	array	Array of media asset URLs
`engagement.likes`	integer	Number of likes/hearts
`engagement.comments`	integer	Number of comments
`engagement.shares`	integer	Number of shares/retweets
`engagement.views`	integer	Number of views (videos)
`engagement.total`	integer	Total engagement (likes + comments + shares)
`author.username`	string	Author's username/handle
`author.display_name`	string\|null	Author's display name
`author.profile_url`	string\|null	URL to author's profile
`author.avatar_url`	string\|null	URL to author's avatar image
`hashtags`	array	Array of hashtags (without #)
`mentions`	array	Array of mentioned usernames (without @)
`scraped_at`	string\|null	When the post was scraped

List Response Metadata

Responses that return posts include additional metadata:

{
  "success": true,
  "data": {
    "platform": "tiktok",
    "username": "charlidamelio",
    "posts_count": 50,
    "posts_charged": 50,
    "remaining_balance": 950,
    "posts": [
      // Array of post objects
    ]
  }
}
    

Metadata Fields

Field	Type	Description
`posts_count`	integer	Number of posts returned in this response
`posts_charged`	integer	Number of credits deducted from your balance
`remaining_balance`	integer	Your credit balance after this request

HTTP Status Codes

Status	Meaning
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or request format
401	Unauthorized - Invalid or missing API token
402	Payment Required - Insufficient credit balance
403	Forbidden - Account inactive or access denied
404	Not Found - Endpoint or resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end