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 · 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": "link",
  "collection_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "collection_names": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "link": "link",
  "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

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: 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: 100 · required

Array of video URLs to track

label_ids

string[]

Optional label IDs to apply to all tracked videos

Bulk Track Videos › Responses

All videos tracked successfully

success

boolean

object

object[]

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.example.com/path/to/resource"
  ],
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}
'

shell

Example Request Body

{
  "links": [
    "https://www.example.com/path/to/resource"
  ],
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "success": true,
  "summary": {
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "alreadyExists": 0
  },
  "results": [
    {
      "type": "account",
      "url": "url",
      "success": true,
      "error": "error",
      "videoId": "videoId",
      "wasExisting": true
    }
  ]
}

json

application/json

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: 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: 100 · required

Array of video IDs (UUIDs) or URLs to stop tracking

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

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

Username of the account that posted the video

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

Shortimize API

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.

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 · 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": "link",
  "collection_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "collection_names": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "link": "link",
  "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

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

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: 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: 100 · required

Array of video URLs to track

label_ids

string[]

Optional label IDs to apply to all tracked videos

Bulk Track Videos › Responses

All videos tracked successfully

success

boolean

object

object[]

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.example.com/path/to/resource"
  ],
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}
'

shell

Example Request Body

{
  "links": [
    "https://www.example.com/path/to/resource"
  ],
  "label_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "success": true,
  "summary": {
    "total": 0,
    "succeeded": 0,
    "failed": 0,
    "alreadyExists": 0
  },
  "results": [
    {
      "type": "account",
      "url": "url",
      "success": true,
      "error": "error",
      "videoId": "videoId",
      "wasExisting": true
    }
  ]
}

json

application/json

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: 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: 100 · required

Array of video IDs (UUIDs) or URLs to stop tracking

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.

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

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.

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.

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

Username of the account that posted the video

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