Shortimize

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "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."
    },
    "paginated": {
      "type": "boolean",
      "default": false,
      "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
    },
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Page number for pagination (requires paginated=true)"
    },
    "limit": {
      "type": "integer",
      "default": 5000,
      "minimum": 1,
      "maximum": 5000,
      "description": "Number of items to return per page"
    },
    "order_by": {
      "type": "string",
      "default": "checked_at",
      "description": "Field to order results by"
    },
    "order_direction": {
      "type": "string",
      "default": "desc",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction of ordering (ascending or descending)"
    }
  }
}

Track an account and link it to your organisation in Shortimize.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "format": "uri",
      "description": "The URL of the account to start tracked"
    },
    "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"
    },
    "tracking_type": {
      "type": "string",
      "description": "Optional tracking type to use (e.g., 'latest_30', 'latest_200'). If left empty, will use the organisation default."
    }
  },
  "required": [
    "link"
  ]
}

Stop tracking an account linked to your organisation.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID (UUID) or URL of the account to stop tracking"
    }
  },
  "required": [
    "id"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "links": {
      "type": "array",
      "minItems": 1,
      "maxItems": 500,
      "items": {
        "type": "string",
        "format": "uri",
        "description": "The URL of the account to track"
      },
      "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": {
      "type": "string",
      "enum": [
        "latest_10",
        "latest_30",
        "latest_60",
        "latest_100",
        "latest_200",
        "latest_500",
        "all_videos"
      ],
      "description": "Optional tracking type. Defaults to organisation setting."
    }
  },
  "required": [
    "links"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 500,
      "items": {
        "type": "string"
      },
      "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"
    }
  },
  "required": [
    "ids"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Page number for pagination"
    },
    "limit": {
      "type": "integer",
      "default": 5000,
      "minimum": 1,
      "maximum": 5000,
      "description": "Number of items to return per page"
    },
    "order_by": {
      "type": "string",
      "default": "latest_updated_at",
      "enum": [
        "created_at",
        "uploaded_at",
        "latest_views",
        "latest_likes",
        "latest_comments",
        "latest_bookmarks",
        "latest_shares",
        "latest_engagement",
        "latest_updated_at"
      ],
      "description": "Field to order results by"
    },
    "order_direction": {
      "type": "string",
      "default": "desc",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction of ordering (ascending or descending)"
    },
    "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."
    },
    "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)"
    },
    "uploaded_at_end": {
      "type": "string",
      "format": "date",
      "description": "Filter videos uploaded on or before this date (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)"
    },
    "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)"
    },
    "ad_info_shop": {
      "type": "boolean",
      "description": "Filter TikTok shop ads (true/false)"
    },
    "ad_product_id_shop": {
      "type": "boolean",
      "description": "Filter TikTok shop ads that have a product id. (true)"
    },
    "has_metrics": {
      "type": "boolean",
      "description": "Only get videos which have been retrieved atleast once (metrics are not null)."
    },
    "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."
    }
  }
}

Track a video and link it to your organisation in Shortimize. A direct URL to the video analysis on Shortimize will be returned.

{
  "type": "object",
  "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"
    }
  },
  "required": [
    "link"
  ]
}

Stops tracking specific videos in Shortimize. This operation allows you to selectively pause data collection for individual videos while maintaining their histo

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID (UUID) or URL of the video to stop tracking"
    }
  },
  "required": [
    "id"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "links": {
      "type": "array",
      "minItems": 1,
      "maxItems": 500,
      "items": {
        "type": "string",
        "format": "uri",
        "description": "The URL of the video to track"
      },
      "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"
    }
  },
  "required": [
    "links"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 500,
      "items": {
        "type": "string"
      },
      "description": "Array of video IDs (UUIDs) or URLs to stop tracking"
    }
  },
  "required": [
    "ids"
  ]
}

Test your AUTH key against our service, if successful your organisation name will be returned.

{
  "type": "object",
  "properties": {}
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "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)."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "End date (inclusive) in YYYY-MM-DD format."
    }
  }
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "Video identifier - can be a UUID or video URL (URL-encoded)"
    }
  },
  "required": [
    "ad_id"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "Video identifier - can be a UUID or video 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)."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "End date (inclusive) in YYYY-MM-DD format"
    }
  },
  "required": [
    "ad_id"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "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)."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "End date (inclusive) in YYYY-MM-DD format"
    }
  },
  "required": [
    "account_id"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account identifier - can be a UUID or account URL (URL-encoded)"
    }
  },
  "required": [
    "account_id"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "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)"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Filter videos uploaded on or before this date (inclusive, YYYY-MM-DD)"
    },
    "paginated": {
      "type": "boolean",
      "default": false,
      "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
    },
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Page number for pagination (requires paginated=true)"
    },
    "limit": {
      "type": "integer",
      "default": 5000,
      "minimum": 1,
      "maximum": 5000,
      "description": "Number of items to return per page"
    },
    "order_by": {
      "type": "string",
      "default": "uploaded_at",
      "description": "Field to order results by"
    },
    "order_direction": {
      "type": "string",
      "default": "desc",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction of ordering (ascending or descending)"
    }
  },
  "required": [
    "account_id"
  ]
}

Retrieves the total count of videos being tracked by your organization in Shortimize.

{
  "type": "object",
  "properties": {}
}

Retrieves the total number of accounts currently being tracked by your organization in Shortimize.

{
  "type": "object",
  "properties": {}
}

Refresh an account, if it wasn't updated in the last 4 hours.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The URL or ID (UUID) of the account to refresh"
    }
  },
  "required": [
    "link"
  ]
}

Refresh a video, if it wasn't updated in the last 4 hours.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The URL or ID (UUID) of the video to refresh"
    }
  },
  "required": [
    "link"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "parent_id": {
      "type": "string",
      "description": "Filter collections by parent ID. Use 'null' for root-level collections only."
    },
    "include_children": {
      "type": "boolean",
      "default": false,
      "description": "Include child collections in the response"
    },
    "paginated": {
      "type": "boolean",
      "default": false,
      "description": "Set to true to receive paginated response with {data, pagination} format instead of {data, count}"
    },
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Page number for pagination (requires paginated=true)"
    },
    "limit": {
      "type": "integer",
      "default": 5000,
      "minimum": 1,
      "maximum": 5000,
      "description": "Number of items to return per page"
    },
    "order_by": {
      "type": "string",
      "default": "created_at",
      "description": "Field to order results by"
    },
    "order_direction": {
      "type": "string",
      "default": "desc",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction of ordering (ascending or descending)"
    }
  }
}

Creates a new collection for organizing accounts and videos.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Collection name",
      "maxLength": 100
    },
    "parent_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional parent collection ID for nested collections"
    },
    "access": {
      "type": "string",
      "enum": [
        "private",
        "public",
        "protected"
      ],
      "default": "private",
      "description": "Access level for the collection"
    }
  },
  "required": [
    "name"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "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"
    }
  },
  "required": [
    "collection_id"
  ]
}

Updates a collection's properties.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "maxLength": 100
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "access": {
      "type": "string",
      "enum": [
        "private",
        "public",
        "protected"
      ]
    },
    "password": {
      "type": "string",
      "minLength": 8,
      "description": "Password for protected collections"
    },
    "display_settings": {
      "type": "object",
      "description": "Display settings for public collections"
    }
  },
  "required": [
    "collection_id"
  ]
}

Deletes a collection. This will also remove all associations with accounts and videos.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "collection_id"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "paginated": {
      "type": "boolean",
      "default": false,
      "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
    },
    "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"
    },
    "order_direction": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Order direction"
    }
  },
  "required": [
    "collection_id"
  ]
}

Adds one or more videos to a collection.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "video_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of video IDs to add to the collection"
    }
  },
  "required": [
    "collection_id",
    "video_ids"
  ]
}

Removes one or more videos from a collection.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "video_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of video IDs to remove from the collection"
    }
  },
  "required": [
    "collection_id",
    "video_ids"
  ]
}

**All tiers** — Limited/Basic: 1 result with masked metrics. Premium: full access.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "paginated": {
      "type": "boolean",
      "default": false,
      "description": "Set to true to receive paginated response with {data, pagination} format instead of raw array"
    },
    "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"
    },
    "order_direction": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc",
      "description": "Order direction"
    }
  },
  "required": [
    "collection_id"
  ]
}

Adds one or more accounts to a collection.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "account_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of account IDs to add to the collection"
    }
  },
  "required": [
    "collection_id",
    "account_ids"
  ]
}

Removes one or more accounts from a collection.

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "string",
      "format": "uuid"
    },
    "account_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Array of account IDs to remove from the collection"
    }
  },
  "required": [
    "collection_id",
    "account_ids"
  ]
}