Video Management

Endpointhttps://api.shortimize.com

Manage and track video content

Get All Videos

GET

https://api.shortimize.com

/videos

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

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: 5 (limited) / 15 (basic) / 30 (premium) requests per minute

Get All Videos › query Parameters

page

integer · min: 1

Page number for pagination

Default: 1

limit

integer · min: 1 · max: 5000

Number of items to return per page

Default: 5000

order_by

string · 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_direction

string · enum

Direction of ordering (ascending or descending)

Enum values:

asc

desc

Default: desc

username

string

Filter videos by specific username

linked_account_id

string · uuid

Filter videos by specific linked account ID

uploaded_at_start

string · date

Filter videos uploaded on or after this date (inclusive)

uploaded_at_end

string · date

Filter videos uploaded on or before this date (inclusive)

latest_updated_at_start

string · date-time

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

latest_updated_at_end

string · date-time

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

ad_info_shop

boolean

Filter TikTok shop ads (true/false)

ad_product_id_shop

boolean

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

has_metrics

boolean

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

collections

string

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

Authorization

string · required

Bearer token for authentication

Get All Videos › Responses

Successful response with a list of videos and their detailed information

object[]

object

GET/videos

curl --request GET \
  --url https://api.shortimize.com/videos \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "data": [
    {
      "organisation_id": "00000000-0000-0000-0000-000000000000",
      "ad_id": "00000000-0000-0000-0000-000000000000",
      "username": "username",
      "platform": "tiktok",
      "ad_link": "https://www.example.com/path/to/resource",
      "created_at": "2024-08-25T15:00:00Z",
      "removed": true,
      "linked_account_id": "00000000-0000-0000-0000-000000000000",
      "uploaded_at": "2024-08-25",
      "song_name": "song_name",
      "song_link": "song_link",
      "video_length": "video_length",
      "title": "title",
      "not_safe": true,
      "private": true,
      "hidden_stats": true,
      "latest_views": 0,
      "latest_likes": 0,
      "latest_comments": 0,
      "latest_bookmarks": 0,
      "latest_shares": 0,
      "latest_engagement": 0,
      "latest_updated_at": "2024-08-25T15:00:00Z",
      "outlier_multiplier": 0,
      "increase_1d": 0,
      "increase_7d": 0,
      "increase_14d": 0,
      "increase_30d": 0,
      "ad_info_shop": true,
      "ad_is_ad": true,
      "ad_product_id_shop": "ad_product_id_shop",
      "label_ids": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "label_names": [
        "string"
      ]
    }
  ],
  "pagination": {
    "total": 0,
    "page": 0,
    "limit": 0,
    "total_pages": 0,
    "has_more": true,
    "order_by": "order_by",
    "order_direction": "order_direction"
  },
  "filters": {
    "username": "username",
    "linked_account_id": "linked_account_id",
    "uploaded_at_range": {
      "start": "2024-08-25",
      "end": "2024-08-25"
    },
    "ad_info_shop": true,
    "has_metrics": true,
    "collections": [
      "string"
    ]
  }
}

json

application/json

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: 5 (limited) / 15 (basic) / 120 (premium) requests per minute

Track Video › Headers

Authorization

string · required

Bearer token for authentication

content-type

string · enum · required

Must be set to application/json

Enum values:

application/json

Track Video › Request Body

link

string · uri · required

The URL of the video to be tracked

collection_ids

string[]

Optional list of collection UUIDs to associate with the video

collection_names

string[]

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

Track Video › Responses

Successful operation

error

string

Only present if the video is already being tracked.

directUrl

string · uri

Shortened URL to the video analysis on the dashboard

videoId

string

A UUID representing the video in our system

POST/videos

curl --request POST \
  --url https://api.shortimize.com/videos \
  --header 'Authorization: <string>' \
  --header 'Content-Type: application/json' \
  --header 'content-type: <string>' \
  --data '
{
  "link": "https://www.example.com/path/to/resource",
  "collection_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "collection_names": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "link": "https://www.example.com/path/to/resource",
  "collection_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "collection_names": [
    "string"
  ]
}

json

Example Responses

{
  "error": "This video is already being tracked in the organisation.",
  "directUrl": "https://app.shortimize.com/video/<PLATFORM>/<VIDEO_ID>",
  "videoId": "xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxxxx"
}

json

application/json

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: 5 (limited) / 15 (basic) / 120 (premium) requests per minute

Stop Tracking Video › Headers

Authorization

string · required

Bearer token for authentication

Stop Tracking Video › Request Body

id

string · required

The ID (UUID) or URL of the video to stop tracking

Stop Tracking Video › Responses

Successful operation

message

string

Success message confirming the operation

Bulk Track Videos

POST

https://api.shortimize.com

/videos/bulk

Start tracking up to 500 videos in one request.

Send a list of links in links. Each one is handled on its own, so a bad link does not stop the rest - you get one entry per link back in results, saying whether it was newly tracked, already tracked, or failed.

Reading the response

summary gives you the counts at a glance.
Each entry in results has a status: tracked, already_tracked, or failed.
A failed entry also has a plain-language error, a stable code, and retryable. If retryable is true, sending that link again will usually work - resend just those links, not the whole batch.
warnings holds anything worth knowing that did not fail the request.

When the data starts arriving Requests of 50 links or fewer start fetching data straight away. Larger requests are still saved and tracked, but the data is collected by the scheduled update rather than immediately - this stops one big import from holding up everyone else. trackingEnqueued tells you which happened. Send 50 links or fewer per request if you need the data to start arriving right away.

Status codes 200 every link was saved. 207 some were saved and some failed. 422 none could be saved. For 207 and 422, read results to see why.

Rate Limit: 5 (limited) / 15 (basic) / 120 (premium) requests per minute

Bulk Track Videos › Headers

Authorization

string · required

Bearer token for authentication

content-type

string · enum · required

Must be set to application/json

Enum values:

application/json

Bulk Track Videos › Request Body

links

string[] · minItems: 1 · maxItems: 500 · required

The videos to start tracking, as a list of links. Between 1 and 500 of them.

label_ids

string[]

Optional label IDs to apply to all tracked videos

Bulk Track Videos › Responses

Every link was saved. Some may have been tracked already - check each entry's status.

success

boolean

True only when every link succeeded. Check the results array when this is false.

object

object[]

One entry per link. If you send the same link more than once it appears here once, so this array can be shorter than the list you sent.

trackingEnqueued

boolean

Whether we started fetching data for every item in this request. False when the request was over the immediate-fetch threshold, or when a free-plan organisation sent more than the preview allowance (in which case some items may still have been fetched). Items are saved and tracked either way. Paid plans have the rest collected by the scheduled update; free plans do not, and the warnings will say so.

warnings

string[]

Things worth knowing that did not fail the request, written in plain language. Empty when there is nothing to report.

object

Only present for an organisation with no active subscription, listing the items that were saved but whose data will not be fetched. On the free plan only the first few items of a batch are collected.

POST/videos/bulk

curl --request POST \
  --url https://api.shortimize.com/videos/bulk \
  --header 'Authorization: <string>' \
  --header 'Content-Type: application/json' \
  --header 'content-type: <string>' \
  --data '
{
  "links": [
    "https://www.tiktok.com/@nike/video/7301234567890123456"
  ],
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}
'

shell

Example Request Body

{
  "links": [
    "https://www.tiktok.com/@nike/video/7301234567890123456"
  ],
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "success": true,
  "summary": {
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "alreadyExists": 0,
    "retryable": 0
  },
  "results": [
    {
      "type": "account",
      "url": "url",
      "status": "tracked",
      "success": true,
      "error": "This shortened link could not be expanded in time. Please retry this link.",
      "code": "invalid_url",
      "retryable": true,
      "videoId": "00000000-0000-0000-0000-000000000000",
      "wasExisting": true
    }
  ],
  "trackingEnqueued": true,
  "warnings": [
    "This request had 120 links, which is more than 50, so we did not start fetching their data right away. Everything was saved and is being tracked - the scheduled update will collect the data shortly."
  ],
  "pendingTmvQueue": {
    "accounts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "platform": "platform"
      }
    ],
    "videos": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "platform": "platform"
      }
    ]
  }
}

json

application/json

Bulk Stop Tracking Videos

DELETE

https://api.shortimize.com

/videos/bulk

Stop tracking up to 500 videos in one request.

Send a list in ids. Each entry can be the video's id or the link you originally tracked - we look up links for you. Historical data stays available; this only stops new data being collected.

If a link cannot be matched to something you track, the whole request fails with 404 naming the links that did not match, before anything is removed. Entries given as ids are not checked up front, so a request of ids can partly succeed and return 207 - read the response to see which ones did.

Rate Limit: 5 (limited) / 15 (basic) / 120 (premium) requests per minute

Bulk Stop Tracking Videos › Headers

Authorization

string · required

Bearer token for authentication

Bulk Stop Tracking Videos › Request Body

ids

string[] · minItems: 1 · maxItems: 500 · required

The videos to stop tracking. Each entry is either an id or the link you tracked. Between 1 and 500 of them.

Bulk Stop Tracking Videos › Responses

All videos successfully stopped tracking

success

boolean

object

object[]

Get Specific Video

GET

https://api.shortimize.com

/videos/{ad_id}

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

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: 5 (limited) / 15 (basic) / 30 (premium) requests per minute

Get Specific Video › path Parameters

ad_id

string · required

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

Get Specific Video › Headers

Authorization

string · required

Bearer token for authentication

Get Specific Video › Responses

Successful response with detailed information about the specific video

organisation_id

string · uuid

Unique identifier for your organization

ad_id

string · uuid

Unique identifier for the video

username

string

Username of the account that posted the video. May carry a '~~' disambiguation suffix ('handle~~<platform_creator_id>') for Facebook accounts: Facebook permits two genuinely different profiles to share one display handle, and the suffix keeps their stats separate. Treat the full string as canonical in API calls; strip everything from '~' onward for display.

platform

string · enum

Social media platform where the video is posted

Enum values:

tiktok

instagram

youtube

ad_link

string · uri

URL of the video

created_at

string · date-time

Timestamp when the video was added to Shortimize

removed

boolean

Indicates if the video has been removed from tracking

linked_account_id

string · uuid

Unique identifier of the linked account

uploaded_at

string | null · date

Date when the video was uploaded to the platform

song_name

string | null

Name of the song used in the video

song_link

string | null

Link to the song used in the video

video_length

string | null

Length of the video in seconds

title

string

Title or caption of the video

not_safe

boolean

Indicates if the video is flagged as not safe for work

private

boolean

Indicates if the video is set to private

hidden_stats

boolean

Indicates if the video's statistics are hidden

latest_views

integer

Most recent count of views

latest_likes

integer

Most recent count of likes

latest_comments

integer

Most recent count of comments

latest_bookmarks

integer

Most recent count of bookmarks

latest_shares

integer

Most recent count of shares

latest_engagement

integer | null

Most recent count of total engagement

latest_updated_at

string · date-time

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

outlier_multiplier

number

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

increase_1d

number

Percentage increase in views over the last day

increase_7d

number

Percentage increase in views over the last 7 days

increase_14d

number

Percentage increase in views over the last 14 days

increase_30d

number

Percentage increase in views over the last 30 days

ad_info_shop

boolean

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

label_ids

array | null

Array of collection/label IDs associated with the video

label_names

array | null

Array of collection/label names associated with the video

GET/videos/{ad_id}

curl --request GET \
  --url https://api.shortimize.com/videos/:ad_id \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "organisation_id": "00000000-0000-0000-0000-000000000000",
  "ad_id": "00000000-0000-0000-0000-000000000000",
  "username": "username",
  "platform": "tiktok",
  "ad_link": "https://www.example.com/path/to/resource",
  "created_at": "2024-08-25T15:00:00Z",
  "removed": true,
  "linked_account_id": "00000000-0000-0000-0000-000000000000",
  "uploaded_at": "2024-08-25",
  "song_name": "song_name",
  "song_link": "song_link",
  "video_length": "video_length",
  "title": "title",
  "not_safe": true,
  "private": true,
  "hidden_stats": true,
  "latest_views": 0,
  "latest_likes": 0,
  "latest_comments": 0,
  "latest_bookmarks": 0,
  "latest_shares": 0,
  "latest_engagement": 0,
  "latest_updated_at": "2024-08-25T15:00:00Z",
  "outlier_multiplier": 0,
  "increase_1d": 0,
  "increase_7d": 0,
  "increase_14d": 0,
  "increase_30d": 0,
  "ad_info_shop": true,
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "label_names": [
    "string"
  ]
}

json

application/json

Stop Tracking Video By ID

DELETE

https://api.shortimize.com

/videos/{ad_id}

Stop tracking a video linked to your organisation via its ad_id.

Use this to pause tracking when you want to stop monitoring a video's performance or remove it from your active tracking portfolio.

Rate Limit: 5 (limited) / 15 (basic) / 120 (premium) requests per minute

Stop Tracking Video By ID › path Parameters

ad_id

string · uuid · required

The UUID of the video to stop tracking

Stop Tracking Video By ID › Headers

Authorization

string · required

Bearer token for authentication

Stop Tracking Video By ID › Responses

Successful operation

message

string

Success message confirming the operation

Get Video History

GET

https://api.shortimize.com

/videos/{ad_id}/history

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

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 (730 days for premium users — historical data beyond 90 days is interpolated from periodic snapshots).

Rate Limit: 5 (limited) / 15 (basic) / 120 (premium) requests per minute

Get Video History › path Parameters

ad_id

string · required

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

Get Video History › query Parameters

start_date

string · date

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

string · date

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

Get Video History › Headers

Authorization

string · required

Bearer token for authentication

Get Video History › Responses

List of daily metrics for the specified video

object[]

date

string · date

views

integer

likes

integer

comments

integer

shares

integer

bookmarks

integer

engagements

integer

Get All Videos Linked To Account

GET

https://api.shortimize.com

/accounts/{account_id}/videos

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

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: 5 (limited) / 15 (basic) / 30 (premium) requests per minute

Get All Videos Linked To Account › path Parameters

account_id

string · required

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

Get All Videos Linked To Account › query Parameters

start_date

string · date

Filter videos uploaded on or after this date (inclusive, YYYY-MM-DD)

end_date

string · date

Filter videos uploaded on or before this date (inclusive, YYYY-MM-DD)

paginated

boolean

Set to true to receive paginated response with {data, pagination} format instead of raw array

Default: false

page

integer · min: 1

Page number for pagination (requires paginated=true)

Default: 1

limit

integer · min: 1 · max: 5000

Number of items to return per page

Default: 5000

order_by

string

Field to order results by

Default: uploaded_at

order_direction

string · enum

Direction of ordering (ascending or descending)

Enum values:

asc

desc

Default: desc

Get All Videos Linked To Account › Headers

Authorization

string · required

Bearer token for authentication

Get All Videos Linked To Account › Responses

Successful response with a list of videos and their detailed information

object[]

organisation_id

string · uuid

Unique identifier for your organization

ad_id

string · uuid

Unique identifier for the video

username

string

platform

string · enum

Social media platform where the video is posted

Enum values:

tiktok

instagram

youtube

ad_link

string · uri

URL of the video

created_at

string · date-time

Timestamp when the video was added to Shortimize

removed

boolean

Indicates if the video has been removed from tracking

linked_account_id

string · uuid

Unique identifier of the linked account

uploaded_at

string | null · date

Date when the video was uploaded to the platform

song_name

string | null

Name of the song used in the video

song_link

string | null

Link to the song used in the video

video_length

string | null

Length of the video in seconds

title

string

Title or caption of the video

not_safe

boolean

Indicates if the video is flagged as not safe for work

private

boolean

Indicates if the video is set to private

hidden_stats

boolean

Indicates if the video's statistics are hidden

latest_views

integer

Most recent count of views

latest_likes

integer

Most recent count of likes

latest_comments

integer

Most recent count of comments

latest_bookmarks

integer

Most recent count of bookmarks

latest_shares

integer

Most recent count of shares

latest_engagement

integer | null

Most recent count of total engagement

latest_updated_at

string · date-time

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

outlier_multiplier

number

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

increase_1d

number

Percentage increase in views over the last day

increase_7d

number

Percentage increase in views over the last 7 days

ad_info_shop

boolean

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

label_ids

array | null

Array of collection/label IDs associated with the video

label_names

array | null

Array of collection/label names associated with the video

GET/accounts/{account_id}/videos

curl --request GET \
  --url https://api.shortimize.com/accounts/:account_id/videos \
  --header 'Authorization: <string>'

shell

Example Responses

[
  {
    "organisation_id": "00000000-0000-0000-0000-000000000000",
    "ad_id": "00000000-0000-0000-0000-000000000000",
    "username": "username",
    "platform": "tiktok",
    "ad_link": "https://www.example.com/path/to/resource",
    "created_at": "2024-08-25T15:00:00Z",
    "removed": true,
    "linked_account_id": "00000000-0000-0000-0000-000000000000",
    "uploaded_at": "2024-08-25",
    "song_name": "song_name",
    "song_link": "song_link",
    "video_length": "video_length",
    "title": "title",
    "not_safe": true,
    "private": true,
    "hidden_stats": true,
    "latest_views": 0,
    "latest_likes": 0,
    "latest_comments": 0,
    "latest_bookmarks": 0,
    "latest_shares": 0,
    "latest_engagement": 0,
    "latest_updated_at": "2024-08-25T15:00:00Z",
    "outlier_multiplier": 0,
    "increase_1d": 0,
    "increase_7d": 0,
    "ad_info_shop": true,
    "label_ids": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "label_names": [
      "string"
    ]
  }
]

json

application/json

Account Management Collection Management