Shortimize API

Video Management

Endpoint:https://api.shortimize.com

Manage and track video content

Get All Videos

GET
https://api.shortimize.com
/videos

Premium Operation - upgrade to Premium API in the app.

Retrieves a list of all videos tracked by your organization in Shortimize. This endpoint provides detailed information about each video, including engagement metrics, content details, and historical performance data.

Use this to get a comprehensive view of your video advertisement portfolio and their performance across different platforms.

Rate Limit: 30 requests per minute

Get All Videos › query Parameters

  • pageinteger · min: 1

    Page number for pagination

    Default: 1
  • limitinteger · min: 1 · max: 20000

    Number of items to return per page

    Default: 20000
  • order_bystring · enum

    Field to order results by

    Enum values:
    created_at
    uploaded_at
    latest_views
    latest_likes
    latest_comments
    latest_bookmarks
    latest_shares
    latest_engagement
    Default: latest_updated_at
  • order_directionstring · enum

    Direction of ordering (ascending or descending)

    Enum values:
    asc
    desc
    Default: desc
  • usernamestring

    Filter videos by specific username

  • linked_account_idstring · uuid

    Filter videos by specific linked account ID

  • uploaded_at_startstring · date

    Filter videos uploaded on or after this date (inclusive)

  • uploaded_at_endstring · date

    Filter videos uploaded on or before this date (inclusive)

  • latest_updated_at_startstring · date-time

    Filter videos which have been last updated on or after this date and time (inclusive)

  • latest_updated_at_endstring · date-time

    Filter videos which have been last updated on or before this date and time (inclusive)

  • ad_info_shopboolean

    Filter TikTok shop ads (true/false)

  • ad_product_id_shopboolean

    Filter TikTok shop ads that have a product id. (true)

  • has_metricsboolean

    Only get videos which have been retrieved atleast once (metrics are not null).

  • collectionsstring

    Optional comma-separated list of collections to filter accounts (e.g. collection1,collection2,collection3)

    Make sure to URL encode them before sending.

Get All Videos › Headers

  • Authorizationstring · required

    Bearer token for authentication

Get All Videos › Responses

Successful response with a list of videos and their detailed information

  • dataobject[]
  • paginationobject
  • filtersobject

Track Video

POST
https://api.shortimize.com
/videos

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

Rate Limit: 120 requests per minute

Track Video › Headers

  • Authorizationstring · required

    Bearer token for authentication

  • content-typestring · enum · required

    Must be set to application/json

    Enum values:
    application/json

Track Video › Request Body

  • linkstring · required

    The URL of the video to be tracked

  • collection_idsstring[]

    Optional list of collection UUIDs to associate with the video

  • collection_namesstring[]

    Optional list of collection names to create and associate with the video

Track Video › Responses

Successful operation

  • errorstring

    Only present if the video is already being tracked.

  • directUrlstring · uri

    Shortened URL to the video analysis on the dashboard

  • videoIdstring

    A UUID representing the video in our system

Stop Tracking Video

DELETE
https://api.shortimize.com
/videos

Stops tracking specific videos in Shortimize. This operation allows you to selectively pause data collection for individual videos while maintaining their historical performance data and metrics. Use this when you need to stop monitoring particular videos that are no longer relevant to your campaign or to optimize your tracking quota. The videos' past performance data remains accessible for analysis and reporting purposes.

Rate Limit: 120 requests per minute

Stop Tracking Video › Headers

  • Authorizationstring · required

    Bearer token for authentication

Stop Tracking Video › Request Body

  • idstring · uri · required

    The ID of the video that you want to stop tracking

Stop Tracking Video › Responses

Successful operation

  • messagestring

    Success message confirming the operation

Bulk Track Videos

POST
https://api.shortimize.com
/videos/bulk

Track multiple videos and link them to your organisation in Shortimize in a single request.

Each video will be processed individually, and a summary of results will be returned. Maximum 100 videos per request.

Rate Limit: 120 requests per minute

Bulk Track Videos › Headers

  • Authorizationstring · required

    Bearer token for authentication

  • content-typestring · enum · required

    Must be set to application/json

    Enum values:
    application/json

Bulk Track Videos › Request Body

  • linksstring[] · minItems: 1 · maxItems: 100 · required

    Array of video URLs to track

  • label_idsstring[]

    Optional label IDs to apply to all tracked videos

Bulk Track Videos › Responses

All videos tracked successfully

  • successboolean
  • summaryobject
  • resultsobject[]

Bulk Stop Tracking Videos

DELETE
https://api.shortimize.com
/videos/bulk

Stop tracking multiple videos linked to your organisation in a single request.

Use this to efficiently remove multiple videos from your active tracking portfolio. Historical performance data remains accessible for analysis.

Rate Limit: 120 requests per minute

Bulk Stop Tracking Videos › Headers

  • Authorizationstring · required

    Bearer token for authentication

Bulk Stop Tracking Videos › Request Body

  • idsstring[] · minItems: 1 · maxItems: 100 · required

    Array of video IDs to stop tracking

Bulk Stop Tracking Videos › Responses

All videos successfully stopped tracking

  • successboolean
  • summaryobject
  • resultsobject[]

Get Specific Video

GET
https://api.shortimize.com
/videos/{ad_id}

Premium Operation - upgrade to Premium API in the app.

Retrieves detailed information about a specific video advertisement linked to your organisation in Shortimize via its ad_id. This endpoint provides comprehensive data including video metrics, performance indicators, and historical data. Use this to get in-depth insights into a particular video's performance, engagement rates, and audience reception.

The data includes:

  • Video identification and platform details
  • Latest engagement metrics (views, likes, comments, shares)
  • Performance statistics (median views, outlier multiplier)
  • Historical data for multiple data points
  • Growth metrics (1-day and 7-day view increases)

This endpoint is crucial for analyzing the success of individual video advertisements and understanding their performance in the context of the account's overall metrics.

Rate Limit: 30 requests per minute

Get Specific Video › path Parameters

  • ad_idstring · required

    Video identifier - can be a UUID or video URL (URL-encoded)

Get Specific Video › Headers

  • Authorizationstring · required

    Bearer token for authentication

Get Specific Video › Responses

Successful response with detailed information about the specific video

  • organisation_idstring · uuid

    Unique identifier for your organization

  • ad_idstring · uuid

    Unique identifier for the video

  • usernamestring

    Username of the account that posted the video

  • platformstring · enum

    Social media platform where the video is posted

    Enum values:
    tiktok
    instagram
    youtube
  • ad_linkstring · uri

    URL of the video

  • created_atstring · date-time

    Timestamp when the video was added to Shortimize

  • removedboolean

    Indicates if the video has been removed from tracking

  • linked_account_idstring · uuid

    Unique identifier of the linked account

  • uploaded_atstring | null · date

    Date when the video was uploaded to the platform

  • song_namestring | null

    Name of the song used in the video

  • song_linkstring | null

    Link to the song used in the video

  • video_lengthstring | null

    Length of the video in seconds

  • titlestring

    Title or caption of the video

  • not_safeboolean

    Indicates if the video is flagged as not safe for work

  • privateboolean

    Indicates if the video is set to private

  • hidden_statsboolean

    Indicates if the video's statistics are hidden

  • latest_viewsinteger

    Most recent count of views

  • latest_likesinteger

    Most recent count of likes

  • latest_commentsinteger

    Most recent count of comments

  • latest_bookmarksinteger

    Most recent count of bookmarks

  • latest_sharesinteger

    Most recent count of shares

  • latest_engagementinteger | null

    Most recent count of total engagement

  • latest_updated_atstring · date-time

    Timestamp of the most recent update to the video's statistics

  • outlier_multipliernumber

    Multiplier indicating how much this video outperforms the account's median

  • increase_1dnumber

    Percentage increase in views over the last day

  • increase_7dnumber

    Percentage increase in views over the last 7 days

  • increase_14dnumber

    Percentage increase in views over the last 14 days

  • increase_30dnumber

    Percentage increase in views over the last 30 days

  • ad_info_shopboolean

    Whether the ad is a tiktok shop ad or not. Only valid for Tiktok videos.

  • label_idsarray | null

    Array of collection/label IDs associated with the video

  • label_namesarray | null

    Array of collection/label names associated with the video

Get Video History

GET
https://api.shortimize.com
/videos/{ad_id}/history

Premium Operation - upgrade to Premium API in the app.

Retrieves daily aggregated metrics for a specific video (ad_id) tracked by your organization. By default if no dates are passed, gets the last 30 days of data. Maximum date range is limited to 90 days.

Rate Limit: 120 requests per minute

Get Video History › path Parameters

  • ad_idstring · required

    Video identifier - can be a UUID or video URL (URL-encoded)

Get Video History › query Parameters

  • start_datestring · date

    Start date (inclusive) in YYYY-MM-DD format

  • end_datestring · date

    End date (inclusive) in YYYY-MM-DD format

Get Video History › Headers

  • Authorizationstring · required

    Bearer token for authentication

Get Video History › Responses

List of daily metrics for the specified video

  • datestring · date
  • viewsinteger
  • likesinteger
  • commentsinteger
  • sharesinteger
  • bookmarksinteger
  • engagementsinteger

Get All Videos Linked To Account

GET
https://api.shortimize.com
/accounts/{account_id}/videos

Premium Operation - upgrade to Premium API in the app.

Retrieves a list of all videos tracked by your organization in Shortimize linked to a specific account. This endpoint provides detailed information about each video, including engagement metrics, content details, and historical performance data.

Use this to get a comprehensive view of your video advertisement portfolio and their performance across different platforms.

Rate Limit: 30 requests per minute

Get All Videos Linked To Account › path Parameters

  • account_idstring · required

    Account identifier - can be a UUID or account URL (URL-encoded)

Get All Videos Linked To Account › Headers

  • Authorizationstring · required

    Bearer token for authentication

Get All Videos Linked To Account › Responses

Successful response with a list of videos and their detailed information

  • organisation_idstring · uuid

    Unique identifier for your organization

  • ad_idstring · uuid

    Unique identifier for the video

  • usernamestring

    Username of the account that posted the video

  • platformstring · enum

    Social media platform where the video is posted

    Enum values:
    tiktok
    instagram
    youtube
  • ad_linkstring · uri

    URL of the video

  • created_atstring · date-time

    Timestamp when the video was added to Shortimize

  • removedboolean

    Indicates if the video has been removed from tracking

  • linked_account_idstring · uuid

    Unique identifier of the linked account

  • uploaded_atstring | null · date

    Date when the video was uploaded to the platform

  • song_namestring | null

    Name of the song used in the video

  • song_linkstring | null

    Link to the song used in the video

  • video_lengthstring | null

    Length of the video in seconds

  • titlestring

    Title or caption of the video

  • not_safeboolean

    Indicates if the video is flagged as not safe for work

  • privateboolean

    Indicates if the video is set to private

  • hidden_statsboolean

    Indicates if the video's statistics are hidden

  • latest_viewsinteger

    Most recent count of views

  • latest_likesinteger

    Most recent count of likes

  • latest_commentsinteger

    Most recent count of comments

  • latest_bookmarksinteger

    Most recent count of bookmarks

  • latest_sharesinteger

    Most recent count of shares

  • latest_engagementinteger | null

    Most recent count of total engagement

  • latest_updated_atstring · date-time

    Timestamp of the most recent update to the video's statistics

  • outlier_multipliernumber

    Multiplier indicating how much this video outperforms the account's median

  • increase_1dnumber

    Percentage increase in views over the last day

  • increase_7dnumber

    Percentage increase in views over the last 7 days

  • ad_info_shopboolean

    Whether the ad is a tiktok shop ad or not. Only valid for Tiktok videos.

  • label_idsarray | null

    Array of collection/label IDs associated with the video

  • label_namesarray | null

    Array of collection/label names associated with the video

Account ManagementCollection Management