Track TikTok, Instagram Reels and YouTube Shorts accounts and videos: views, growth and analytics.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer <API key>; create one in Shortimize under Settings → API & Automation
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Add one or more accounts (account_ids) to the collection identified by collection_id. Use get_collection_accounts to check membership; remove_accounts_from_collection reverses it.
Array of account IDs to add to the collection
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Add one or more accounts (account_ids) to the collection identified by collection_id. Use get_collection_accounts to check membership; remove_accounts_from_collection reverses it.
| Argument | Type | Description |
|---|---|---|
| account_ids* | array | Array of account IDs to add to the collection |
| collection_id* | string |
{
"type": "object",
"required": [
"collection_id",
"account_ids"
],
"properties": {
"account_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100,
"minItems": 1,
"description": "Array of account IDs to add to the collection"
},
"collection_id": {
"type": "string",
"format": "uuid"
}
}
}Add one or more videos (video_ids) to the collection identified by collection_id. Use get_collection_videos to check membership; remove_videos_from_collection reverses it.
| Argument | Type | Description |
|---|---|---|
| video_ids* | array | Array of video IDs to add to the collection |
| collection_id* | string |
{
"type": "object",
"required": [
"collection_id",
"video_ids"
],
"properties": {
"video_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100,
"minItems": 1,
"description": "Array of video IDs to add to the collection"
},
"collection_id": {
"type": "string",
"format": "uuid"
}
}
}Test your AUTH key against our service, if successful your organisation name will be returned.
No arguments.
{
"type": "object",
"properties": {}
}Stop tracking up to 500 accounts in one request. Each entry in ids can be an account id or the link you originally tracked. Historical data stays available; this only stops new data being collected. If a link cannot be matched the whole request fails with 404 before anything is removed; a request of ids can partly succeed.
| Argument | Type | Description |
|---|---|---|
| ids* | array | Array of account IDs (UUIDs) or URLs to stop tracking |
| leave_videos | boolean | If true, videos linked to these accounts will not be removed |
{
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"description": "Array of account IDs (UUIDs) or URLs to stop tracking"
},
"leave_videos": {
"type": "boolean",
"default": false,
"description": "If true, videos linked to these accounts will not be removed"
}
}
}Stop tracking up to 500 videos in one request. Each entry in ids can be a video id or the link you originally tracked. Historical data stays available; this only stops new data being collected. If a link cannot be matched the whole request fails with 404 before anything is removed; a request of ids can partly succeed.
| Argument | Type | Description |
|---|---|---|
| ids* | array | Array of video IDs (UUIDs) or URLs to stop tracking |
{
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"description": "Array of video IDs (UUIDs) or URLs to stop tracking"
}
}
}Start tracking up to 500 accounts in one request. Each link is handled on its own, so one bad link does not stop the rest - the response returns one entry per link with a status of tracked, already_tracked, or failed, and failed entries say whether retrying will help. Send 50 links or fewer if the data needs to start arriving immediately; larger batches are still tracked but are collected by the scheduled update.
| Argument | Type | Description |
|---|---|---|
| links* | array | Array of account URLs to track |
| label_ids | array | Optional label IDs to apply to all tracked accounts |
| tracking_type | string | Optional tracking type. Defaults to organisation setting. |
{
"type": "object",
"required": [
"links"
],
"properties": {
"links": {
"type": "array",
"items": {
"type": "string",
"format": "uri",
"description": "The URL of the account to track"
},
"maxItems": 500,
"minItems": 1,
"description": "Array of account URLs to track"
},
"label_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Optional label IDs to apply to all tracked accounts"
},
"tracking_type": {
"enum": [
"latest_10",
"latest_30",
"latest_60",
"latest_100",
"latest_200",
"latest_500",
"all_videos"
],
"type": "string",
"description": "Optional tracking type. Defaults to organisation setting."
}
}
}Start tracking up to 500 videos in one request. Each link is handled on its own, so one bad link does not stop the rest - the response returns one entry per link with a status of tracked, already_tracked, or failed, and failed entries say whether retrying will help. Send 50 links or fewer if the data needs to start arriving immediately; larger batches are still tracked but are collected by the scheduled update.
| Argument | Type | Description |
|---|---|---|
| links* | array | Array of video URLs to track |
| label_ids | array | Optional label IDs to apply to all tracked videos |
{
"type": "object",
"required": [
"links"
],
"properties": {
"links": {
"type": "array",
"items": {
"type": "string",
"format": "uri",
"description": "The URL of the video to track"
},
"maxItems": 500,
"minItems": 1,
"description": "Array of video URLs to track"
},
"label_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Optional label IDs to apply to all tracked videos"
}
}
}Create a new collection for organizing accounts and videos, with a name and optional parent_id and access. Fill it afterwards with add_videos_to_collection or add_accounts_to_collection.
| Argument | Type | Description |
|---|---|---|
| name* | string | Collection name |
| access | string | Access level for the collection |
| parent_id | string | Optional parent collection ID for nested collections |
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 100,
"description": "Collection name"
},
"access": {
"enum": [
"private",
"public",
"protected"
],
"type": "string",
"default": "private",
"description": "Access level for the collection"
},
"parent_id": {
"type": "string",
"format": "uuid",
"description": "Optional parent collection ID for nested collections"
}
}
}Delete the collection identified by collection_id. This also removes all of its associations with accounts and videos.
| Argument | Type | Description |
|---|---|---|
| collection_id* | string |
{
"type": "object",
"required": [
"collection_id"
],
"properties": {
"collection_id": {
"type": "string",
"format": "uuid"
}
}
}Get one tracked account by account_id (an account UUID or its URL, URL-encoded), with platform, username, bio, follower and following counts, view/like/comment/share totals, median and mean views, percent_outperform_10x/25x and total_videos_tracked. Use it for the current stats of a single account; use get_account_history for its daily trend, get_videos_linked_to_account for its videos and get_all_accounts to find account ids. Returns one account object. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| account_id* | string | Account identifier - can be a UUID or account URL (URL-encoded) |
{
"type": "object",
"required": [
"account_id"
],
"properties": {
"account_id": {
"type": "string",
"description": "Account identifier - can be a UUID or account URL (URL-encoded)"
}
}
}Get daily aggregated metrics (views, likes, comments, shares, bookmarks, engagements, ads_upload_count, total_ads) for one tracked account, identified by account_id. Defaults to the last 30 days; use start_date and end_date (YYYY-MM-DD) to change the range, within the last 90 days (2 years for Premium). Use it to see an account's trend over time; use get_account for its current stats, or get_organisation_history for the whole organisation. Returns an array with one entry per date. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| end_date | string | End date (inclusive) in YYYY-MM-DD format |
| account_id* | string | Account identifier - can be a UUID or account URL (URL-encoded) |
| start_date | string | Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users). |
{
"type": "object",
"required": [
"account_id"
],
"properties": {
"end_date": {
"type": "string",
"format": "date",
"description": "End date (inclusive) in YYYY-MM-DD format"
},
"account_id": {
"type": "string",
"description": "Account identifier - can be a UUID or account URL (URL-encoded)"
},
"start_date": {
"type": "string",
"format": "date",
"description": "Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users)."
}
}
}List every account your organisation tracks (TikTok, Instagram or YouTube profiles), one row per account with username, platform, follower count, view/like/comment/share/bookmark totals, median and mean views, percent_outperform_10x/25x and total_videos_tracked. Use it to find account ids or compare accounts; use get_account for one account, get_account_history for its daily trend, get_collection_accounts for one collection's accounts. The collections filter matches collection names. Returns a plain array, or { data, pagination } when paginated=true. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (requires paginated=true) |
| limit | integer | Number of items to return per page |
| order_by | string | Field to order results by |
| paginated | boolean | Set to true to receive paginated response with {data, pagination} format instead of raw array |
| collections | string | Optional comma-separated list of collection NAMES to filter accounts (e.g. collection1,collection2,collection3). This filter matches on name only — to select a collection by its stable id, use GET /collections/{collection_id}/accounts instead. Make sure to URL encode them before sending. |
| order_direction | string |
List the collections your organisation uses to group accounts and videos, with id, name, parent_id, access (private, public or protected), created_at and hashtags. Optionally list only the children of a parent_id (include_children). Use it to find a collection_id for get_collection, get_collection_videos, get_collection_accounts or the add/remove tools. Returns { data, count }. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (requires paginated=true) |
| limit | integer | Number of items to return per page |
| order_by | string | Field to order results by |
| paginated | boolean | Set to true to receive paginated response with {data, pagination} format instead of {data, count} |
| parent_id | string | Filter collections by parent ID. Use 'null' for root-level collections only. |
| order_direction | string | Direction of ordering (ascending or descending) |
| include_children | boolean | Include child collections in the response |
List the videos your organisation tracks, one row per video with ad_id, platform, username, title, upload date, latest views/likes/comments/shares/bookmarks, outlier_multiplier and increase_1d/7d/14d/30d growth. Filter by username, linked_account_id, upload or last-update date range, has_metrics or collection names. Use it to search across all videos; use get_video for one video, get_videos_linked_to_account for one account's videos, get_collection_videos for one collection's videos. Returns { data, pagination, filters }. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| limit | integer | Number of items to return per page |
| order_by | string | Field to order results by |
| username | string | Filter videos by specific username. Exact match — Facebook usernames may carry a '~' disambiguation suffix ('handle~<platform_creator_id>') when two distinct profiles share a handle; pass the full suffixed string as returned by the API. |
| collections | string | Optional comma-separated list of collections to filter videos by. Accepts either collection names (e.g. collection1,collection2) or collection ids as returned by GET /collections (e.g. 136092c1-11db-4f29-95f8-f96b3eb0baad). Do not mix the two forms in one request — a mixed list is rejected with 400. Prefer ids: a collection can be renamed, and a name that no longer matches returns zero results rather than an error. Make sure to URL encode them before sending. |
Get one collection by collection_id, with name, parent_id, access, hashtags and display_settings. Set include_counts=true to include video_count and account_count. Use it to inspect a single collection; use get_collection_videos or get_collection_accounts to see what it contains and get_all_collections to find ids. Returns one collection object. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| collection_id* | string | The unique identifier of the collection |
| include_counts | boolean | Include video and account counts |
{
"type": "object",
"required": [
"collection_id"
],
"properties": {
"collection_id": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the collection"
},
"include_counts": {
"type": "boolean",
"default": false,
"description": "Include video and account counts"
}
}
}List the accounts that belong to one collection, identified by collection_id, with sorting and pagination (page, limit, order_by, order_direction). Use it to review one collection's accounts; use get_all_accounts to search across all accounts, and add_accounts_to_collection or remove_accounts_from_collection to change membership. Returns { data, pagination }. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (default: 1) |
| limit | integer | Items per page (default: 100, max: 5000) |
| order_by | string | Field to order by |
| paginated | boolean | Set to true to receive paginated response with {data, pagination} format instead of raw array |
| collection_id* | string | |
| order_direction | string | Order direction |
{
"type": "object",
"required": [
"collection_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"description": "Page number (default: 1)"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 5000,
"description": "Items per page (default: 100, max: 5000)"
},
"order_by": {
"type": "string",
"default": "created_at",
"description": "Field to order by"
},
"paginated": {
"type": "boolean",
"default": false,
"description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
},
"collection_id": {
"type": "string",
"format": "uuid"
},
"order_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Order direction"
}
}
}List the videos that belong to one collection, identified by collection_id, with sorting and pagination (page, limit, order_by, order_direction). Use it to review one collection's videos; use get_all_videos to search across all videos, and add_videos_to_collection or remove_videos_from_collection to change membership. Returns { data, pagination }. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number (default: 1) |
| limit | integer | Items per page (default: 100, max: 5000) |
| order_by | string | Field to order by |
| paginated | boolean | Set to true to receive paginated response with {data, pagination} format instead of raw array |
| collection_id* | string | |
| order_direction | string | Order direction |
{
"type": "object",
"required": [
"collection_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"description": "Page number (default: 1)"
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 5000,
"description": "Items per page (default: 100, max: 5000)"
},
"order_by": {
"type": "string",
"default": "created_at",
"description": "Field to order by"
},
"paginated": {
"type": "boolean",
"default": false,
"description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
},
"collection_id": {
"type": "string",
"format": "uuid"
},
"order_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Order direction"
}
}
}Get daily aggregated metrics (views, likes, comments, shares, bookmarks, engagements, total_ads, ads_upload_count) across everything your organisation tracks. Defaults to the last 30 days; use start_date and end_date (YYYY-MM-DD) to change the range, within the last 90 days (2 years for Premium). Use it for an organisation-wide trend; use get_account_history or get_video_history for a single account or video. Returns an array with one entry per date. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| end_date | string | End date (inclusive) in YYYY-MM-DD format. |
| start_date | string | Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users). |
{
"type": "object",
"properties": {
"end_date": {
"type": "string",
"format": "date",
"description": "End date (inclusive) in YYYY-MM-DD format."
},
"start_date": {
"type": "string",
"format": "date",
"description": "Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users)."
}
}
}Get one tracked video by ad_id (a video UUID or its URL, URL-encoded), with platform, username, title, upload date, latest views/likes/comments/shares/bookmarks, outlier_multiplier and increase_1d/7d/14d/30d growth. Use it for the current numbers of a single video; use get_video_history for its daily metrics over time and get_all_videos to find ad_ids. Returns one video object. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| ad_id* | string | Video identifier - can be a UUID or video URL (URL-encoded) |
{
"type": "object",
"required": [
"ad_id"
],
"properties": {
"ad_id": {
"type": "string",
"description": "Video identifier - can be a UUID or video URL (URL-encoded)"
}
}
}Get daily metrics (views, likes, comments, shares, bookmarks, engagements) for one tracked video, identified by ad_id. Defaults to the last 30 days; use start_date and end_date (YYYY-MM-DD) to change the range, up to 90 days (730 for Premium, where data older than 90 days is interpolated from periodic snapshots). Use it to see how a video grew over time; use get_video for its current numbers. Returns an array with one entry per date. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| ad_id* | string | Video identifier - can be a UUID or video URL (URL-encoded) |
| end_date | string | End date (inclusive) in YYYY-MM-DD format |
| start_date | string | Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users). |
{
"type": "object",
"required": [
"ad_id"
],
"properties": {
"ad_id": {
"type": "string",
"description": "Video identifier - can be a UUID or video URL (URL-encoded)"
},
"end_date": {
"type": "string",
"format": "date",
"description": "End date (inclusive) in YYYY-MM-DD format"
},
"start_date": {
"type": "string",
"format": "date",
"description": "Start date (inclusive) in YYYY-MM-DD format. Defaults to 30 days ago if not provided. Cannot be older than 90 days (730 days for premium users)."
}
}
}List the tracked videos that belong to one account, identified by account_id (an account UUID or its URL, URL-encoded), with the same per-video fields as get_all_videos (ad_id, title, latest views/likes/comments/shares, outlier_multiplier, increase_1d/7d). Optionally filter by upload date with start_date and end_date, and sort or paginate. Use it to review one creator's videos; use get_all_videos to search across every account. Returns a plain array, or { data, pagination } when paginated=true. Tier limits: Limited/Basic keys get 1 result with masked metrics; Premium gets full access.
| Argument | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (requires paginated=true) |
| limit | integer | Number of items to return per page |
| end_date | string | Filter videos uploaded on or before this date (inclusive, YYYY-MM-DD) |
| order_by | string | Field to order results by |
| paginated | boolean | Set to true to receive paginated response with {data, pagination} format instead of raw array |
| account_id* | string | Account identifier - can be a UUID or account URL (URL-encoded) |
| start_date |
Refresh an account, if it wasn't updated in the last 4 hours.
| Argument | Type | Description |
|---|---|---|
| link* | string | The URL or ID (UUID) of the account to refresh |
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"description": "The URL or ID (UUID) of the account to refresh"
}
}
}Refresh a video, if it wasn't updated in the last 4 hours.
| Argument | Type | Description |
|---|---|---|
| link* | string | The URL or ID (UUID) of the video to refresh |
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"description": "The URL or ID (UUID) of the video to refresh"
}
}
}Remove one or more accounts (account_ids) from the collection identified by collection_id, ending their membership in that collection. Use get_collection_accounts to check what remains.
| Argument | Type | Description |
|---|---|---|
| account_ids* | array | Array of account IDs to remove from the collection |
| collection_id* | string |
{
"type": "object",
"required": [
"collection_id",
"account_ids"
],
"properties": {
"account_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100,
"minItems": 1,
"description": "Array of account IDs to remove from the collection"
},
"collection_id": {
"type": "string",
"format": "uuid"
}
}
}Remove one or more videos (video_ids) from the collection identified by collection_id, ending their membership in that collection. Use get_collection_videos to check what remains.
| Argument | Type | Description |
|---|---|---|
| video_ids* | array | Array of video IDs to remove from the collection |
| collection_id* | string |
{
"type": "object",
"required": [
"collection_id",
"video_ids"
],
"properties": {
"video_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 100,
"minItems": 1,
"description": "Array of video IDs to remove from the collection"
},
"collection_id": {
"type": "string",
"format": "uuid"
}
}
}Stop tracking an account linked to your organisation, identified by its ID (UUID) or URL. Use it to pause monitoring an account that is no longer relevant or to free tracking quota; use bulk_stop_tracking_accounts for many at once.
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID (UUID) or URL of the account to stop tracking |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID (UUID) or URL of the account to stop tracking"
}
}
}Stop tracking a video in Shortimize, identified by its ID (UUID) or URL. Historical performance data stays available; this only stops new data being collected. Use bulk_stop_tracking_videos for many at once.
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID (UUID) or URL of the video to stop tracking |
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID (UUID) or URL of the video to stop tracking"
}
}
}Retrieves the total number of accounts currently being tracked by your organization in Shortimize.
No arguments.
{
"type": "object",
"properties": {}
}Retrieves the total count of videos being tracked by your organization in Shortimize.
No arguments.
{
"type": "object",
"properties": {}
}Track an account and link it to your organisation in Shortimize.
| Argument | Type | Description |
|---|---|---|
| link* | string | The URL of the account to start tracked |
| tracking_type | string | Optional tracking type to use (e.g., 'latest_30', 'latest_200'). If left empty, will use the organisation default. |
| collection_ids | array | Optional list of collection UUIDs to associate with the account |
| collection_names | array | Optional list of collection names to create and associate with the account |
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"format": "uri",
"description": "The URL of the account to start tracked"
},
"tracking_type": {
"type": "string",
"description": "Optional tracking type to use (e.g., 'latest_30', 'latest_200'). If left empty, will use the organisation default."
},
"collection_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Optional list of collection UUIDs to associate with the account"
},
"collection_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of collection names to create and associate with the account"
}
}
}Track a video and link it to your organisation in Shortimize. A direct URL to the video analysis on Shortimize will be returned.
| Argument | Type | Description |
|---|---|---|
| link* | string | The URL of the video to be tracked |
| collection_ids | array | Optional list of collection UUIDs to associate with the video |
| collection_names | array | Optional list of collection names to create and associate with the video |
{
"type": "object",
"required": [
"link"
],
"properties": {
"link": {
"type": "string",
"description": "The URL of the video to be tracked"
},
"collection_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"description": "Optional list of collection UUIDs to associate with the video"
},
"collection_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional list of collection names to create and associate with the video"
}
}
}Update a collection's properties (name, parent_id, access, password, display_settings) by collection_id. Use get_collection first to see the current values.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| access | string | |
| password | string | Password for protected collections |
| parent_id | string | null | |
| collection_id* | string | |
| display_settings | object | Display settings for public collections |
{
"type": "object",
"required": [
"collection_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 100
},
"access": {
"enum": [
"private",
"public",
"protected"
],
"type": "string"
},
"password": {
"type": "string",
"minLength": 8,
"description": "Password for protected collections"
},
"parent_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"collection_id": {
"type": "string",
"format": "uuid"
},
"display_settings": {
"type": "object",
"description": "Display settings for public collections"
}
}
}| Direction of ordering (ascending or descending) |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for pagination (requires paginated=true)"
},
"limit": {
"type": "integer",
"default": 5000,
"maximum": 5000,
"minimum": 1,
"description": "Number of items to return per page"
},
"order_by": {
"type": "string",
"default": "checked_at",
"description": "Field to order results by"
},
"paginated": {
"type": "boolean",
"default": false,
"description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
},
"collections": {
"type": "string",
"description": "Optional comma-separated list of collection NAMES to filter accounts (e.g. collection1,collection2,collection3). This filter matches on name only — to select a collection by its stable id, use GET /collections/{collection_id}/accounts instead.\n\nMake sure to URL encode them before sending."
},
"order_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Direction of ordering (ascending or descending)"
}
}
}{
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for pagination (requires paginated=true)"
},
"limit": {
"type": "integer",
"default": 5000,
"maximum": 5000,
"minimum": 1,
"description": "Number of items to return per page"
},
"order_by": {
"type": "string",
"default": "created_at",
"description": "Field to order results by"
},
"paginated": {
"type": "boolean",
"default": false,
"description": "Set to true to receive paginated response with {data, pagination} format instead of {data, count}"
},
"parent_id": {
"type": "string",
"description": "Filter collections by parent ID. Use 'null' for root-level collections only."
},
"order_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Direction of ordering (ascending or descending)"
},
"include_children": {
"type": "boolean",
"default": false,
"description": "Include child collections in the response"
}
}
}| has_metrics | boolean | Only get videos which have been retrieved atleast once (metrics are not null). |
| ad_info_shop | boolean | Filter TikTok shop ads (true/false) |
| order_direction | string | Direction of ordering (ascending or descending) |
| uploaded_at_end | string | Filter videos uploaded on or before this date (inclusive) |
| linked_account_id | string | Filter videos by specific linked account ID |
| uploaded_at_start | string | Filter videos uploaded on or after this date (inclusive) |
| ad_product_id_shop | boolean | Filter TikTok shop ads that have a product id. (true) |
| latest_updated_at_end | string | Filter videos which have been last updated on or before this date and time (inclusive) |
| latest_updated_at_start | string | Filter videos which have been last updated on or after this date and time (inclusive) |
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for pagination"
},
"limit": {
"type": "integer",
"default": 5000,
"maximum": 5000,
"minimum": 1,
"description": "Number of items to return per page"
},
"order_by": {
"enum": [
"created_at",
"uploaded_at",
"latest_views",
"latest_likes",
"latest_comments",
"latest_bookmarks",
"latest_shares",
"latest_engagement",
"latest_updated_at"
],
"type": "string",
"default": "latest_updated_at",
"description": "Field to order results by"
},
"username": {
"type": "string",
"description": "Filter videos by specific username. Exact match — Facebook usernames may carry a '~' disambiguation suffix ('handle~<platform_creator_id>') when two distinct profiles share a handle; pass the full suffixed string as returned by the API."
},
"collections": {
"type": "string",
"description": "Optional comma-separated list of collections to filter videos by. Accepts either collection names (e.g. collection1,collection2) or collection ids as returned by GET /collections (e.g. 136092c1-11db-4f29-95f8-f96b3eb0baad). Do not mix the two forms in one request — a mixed list is rejected with 400. Prefer ids: a collection can be renamed, and a name that no longer matches returns zero results rather than an error.\n\nMake sure to URL encode them before sending."
},
"has_metrics": {
"type": "boolean",
"description": "Only get videos which have been retrieved atleast once (metrics are not null)."
},
"ad_info_shop": {
"type": "boolean",
"description": "Filter TikTok shop ads (true/false)"
},
"order_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Direction of ordering (ascending or descending)"
},
"uploaded_at_end": {
"type": "string",
"format": "date",
"description": "Filter videos uploaded on or before this date (inclusive)"
},
"linked_account_id": {
"type": "string",
"format": "uuid",
"description": "Filter videos by specific linked account ID"
},
"uploaded_at_start": {
"type": "string",
"format": "date",
"description": "Filter videos uploaded on or after this date (inclusive)"
},
"ad_product_id_shop": {
"type": "boolean",
"description": "Filter TikTok shop ads that have a product id. (true)"
},
"latest_updated_at_end": {
"type": "string",
"format": "date-time",
"description": "Filter videos which have been last updated on or before this date and time (inclusive)"
},
"latest_updated_at_start": {
"type": "string",
"format": "date-time",
"description": "Filter videos which have been last updated on or after this date and time (inclusive)"
}
}
}| string |
| Filter videos uploaded on or after this date (inclusive, YYYY-MM-DD) |
| order_direction | string | Direction of ordering (ascending or descending) |
{
"type": "object",
"required": [
"account_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Page number for pagination (requires paginated=true)"
},
"limit": {
"type": "integer",
"default": 5000,
"maximum": 5000,
"minimum": 1,
"description": "Number of items to return per page"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Filter videos uploaded on or before this date (inclusive, YYYY-MM-DD)"
},
"order_by": {
"type": "string",
"default": "uploaded_at",
"description": "Field to order results by"
},
"paginated": {
"type": "boolean",
"default": false,
"description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
},
"account_id": {
"type": "string",
"description": "Account identifier - can be a UUID or account URL (URL-encoded)"
},
"start_date": {
"type": "string",
"format": "date",
"description": "Filter videos uploaded on or after this date (inclusive, YYYY-MM-DD)"
},
"order_direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"default": "desc",
"description": "Direction of ordering (ascending or descending)"
}
}
}