API docs by Redocly

Social Media Scraping API Documentation | EnsembleData

Download OpenAPI specification:Download


EnsembleData is a social media data provider since 2020. We provide unrestricted and publicly available data extracted in real-time from the social media.

Our platform handles millions of requests daily. We do not enforce rate limits due to our ability to rapidly scale our infrastructure based on demand.

Our platform currency is the so-called units. The units charged per request depend on the complexity of the API and the passed parameters. A detailed description of the units charged can be found in each corresponding API documentation.

Check out our pricing. Any questions? Contact us.

Sign up for a free trial.

Run our APIs with Postman!

Customer

Set of APIs for customers for checking their Social Media Scraping APIs usage. Every customer gets assigned a unique token needed for accessing all our APIs. The token has to be used in all the GET requests sent to our infrastructure.

Get Units Used

This API allows ours clients to check the number of units used on a certain date.

API Pricing (per request): 0 units

API usage examples

  • Token does not exist:
    -> Error code 491 returned.
    Cost: 0 units

  • Token exists:
    -> Units usage for date returned.
    Cost: 0 units


Try the API

query Parameters
date
required
string (Date)
Example: date=2022-11-19

Date for which units usage has to be fetched

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/customer/get-used-units"
params = {
  "date": "2022-11-19",
  "token": "YOUR-TOKEN-HERE"
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Units History

This API allows our clients to check the number of units used in the last N days from today.

API Pricing (per request): 0 units

API usage examples

  • Token does not exist:
    -> Error code 491 returned.
    Cost: 0 units

  • Token exists:
    -> Units usage history returned.
    Cost: 0 units


Try the API

query Parameters
days
required
integer (Days)
Example: days=10

Last N days for which units usage history has to be fetched

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/customer/get-history"
params = {
  "days": 10,
  "token": "YOUR-TOKEN-HERE"
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Tiktok

Real-time Tiktok data scraping API for publicly available data. Scrape Tiktok videos, posts, users information and statistics, and a lot more.

User Posts From Username

Fetch user posts from their username. Depth 1 returns the 10 most recent posts, depth N returns the N * 10 most recent posts. The endpoint only returns posts that are not restricted by TikTok.

API Pricing (per request): 1 + depth units

API usage examples

  • Username does not exist:
    -> 0 posts returned.
    Cost: 1 unit

  • Username exists, but user does not have any posts:
    -> 0 posts returned.
    Cost: 1 unit

  • Username exists, depth is set to 1 and user has more than 10 posts:
    -> 10 posts returned.
    Cost: 2 units

  • Username exists, depth is set to 1 and user has 5 posts:
    -> 5 posts returned.
    Cost: 2 units

  • Username exists, depth is set to 10 and user has more than 100 posts:
    -> 100 posts returned.
    Cost: 11 units

  • Username exists, depth is set to 10 and user only has 45 posts:
    -> 45 posts returned.
    Cost: 6 units

  • Username exists, depth is set to 100, user only has 15 posts more recent than given oldest_createtime:
    -> 15 posts returned.
    Cost: 3 units


Try the API

query Parameters
username
required
string (Username) non-empty
Example: username=daviddobrik

Username of the user.

depth
required
integer (Depth) > 0
Example: depth=1

Abstraction of the API pagination. Depth 1 returns X results, depth N returns N * X results. Note that the exact number of results per depth (X) may differ per endpoint. Please refer to the specific endpoint description for more information.

start_cursor
integer (Start Cursor)
Default: 0

Parameter to manually handle pagination. Each response contains a nextCursor which can be used to retrieve the next page of results by sending it as the next start_cursor. If the nextCursor is not present in the response, it means that there are no more results to retrieve.

oldest_createtime
integer (Oldest Createtime)
Example: oldest_createtime=1667843879

This parameter is used as a stopping condition for fetching posts. If a post older than the provided oldest_createtime is found, the system will stop fetching posts and return the results. For instance, if depth is 10, the system will aim to send 10 requests. However, if an oldest_createtime is set, and we find a post which is older than the oldest_createtime, the system will not send any more requests and return the results. Note: we do not filter out posts older than the provided oldest_createtime before returning the results. Please do this filtering in your own integration if required.

new_version
boolean (New Version)
Default: false

Set to True to enable an alternate version of the TikTok API that returns only the essential fields, resulting in a faster response.

download_video
boolean (Download Video)
Default: false

When new_version=True, set this parameter to True to have the API include the cookie_download field within the video object, which is required for downloading content via the play or download URLs. This will NOT consume more units.

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/tt/user/posts"
params = {
  "username": "daviddobrik",
  "depth": 1,
  "start_cursor": 0,
  "oldest_createtime": 1667843879,
  "new_version": False,
  "download_video": False,
  "token": "YOUR-TOKEN-HERE"
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{}

User Posts From Secuid

Fetch user posts from their secondary user ID. Depth 1 returns the 10 most recent posts, depth N returns the N * 10 most recent posts. The endpoint only returns posts that are not restricted by TikTok.

API Pricing (per request): depth units

API usage examples

  • secUid does not exist:
    -> 0 posts returned.
    Cost: 1 unit

  • secUid exists, but user does not have any posts:
    -> 0 posts returned.
    Cost: 1 unit

  • secUid exists, depth is set to 1 and user has more than 10 posts:
    -> 10 posts returned.
    Cost: 1 unit

  • secUid exists, depth is set to 1 and user has 5 posts:
    -> 5 posts returned.
    Cost: 1 unit

  • secUid exists, depth is set to 10 and user has more than 100 posts:
    -> 100 posts returned.
    Cost: 10 units

  • secUid exists, depth is set to 10 and user only has 45 posts:
    -> 45 posts returned.
    Cost: 5 units

  • secUid exists, depth is set to 100, user only has 15 posts more recent than given oldest_createtime:
    -> 15 posts returned.
    Cost: 2 units


Try the API

query Parameters
secUid
required
string (Secuid) non-empty
Example: secUid=MS4wLjABAAAAQ45IcDZIqrknyl0FDjs7xDlcxlaRE7CcBx1ENxYkWK00UpeKTTlCQWKxq6t9QM6b

The user's secondary user ID.

depth
required
integer (Depth) > 0
Example: depth=1

Abstraction of the API pagination. Depth 1 returns X results, depth N returns N * X results. Note that the exact number of results per depth (X) may differ per endpoint. Please refer to the specific endpoint description for more information.

start_cursor
integer (Start Cursor)
Default: 0

Parameter to manually handle pagination. Each response contains a nextCursor which can be used to retrieve the next page of results by sending it as the next start_cursor. If the nextCursor is not present in the response, it means that there are no more results to retrieve.

oldest_createtime
integer (Oldest Createtime)
Example: oldest_createtime=1667843879

This parameter is used as a stopping condition for fetching posts. If a post older than the provided oldest_createtime is found, the system will stop fetching posts and return the results. For instance, if depth is 10, the system will aim to send 10 requests. However, if an oldest_createtime is set, and we find a post which is older than the oldest_createtime, the system will not send any more requests and return the results. Note: we do not filter out posts older than the provided oldest_createtime before returning the results. Please do this filtering in your own integration if required.

new_version
boolean (New Version)
Default: false

Set to True to enable an alternate version of the TikTok API that returns only the essential fields, resulting in a faster response.

download_video
boolean (Download Video)
Default: false

When new_version=True, set this parameter to True to have the API include the cookie_download field within the video object, which is required for downloading content via the play or download URLs. This will NOT consume more units.

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/tt/user/posts-from-secuid"
params = {
  "secUid": "MS4wLjABAAAAQ45IcDZIqrknyl0FDjs7xDlcxlaRE7CcBx1ENxYkWK00UpeKTTlCQWKxq6t9QM6b",
  "depth": 1,
  "start_cursor": 0,
  "oldest_createtime": 1667843879,
  "new_version": False,
  "download_video": False,
  "token": "YOUR-TOKEN-HERE"
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{}

User Info From Username

Fetch user information and statistics from their username. The data returned includes country, language, biography, profile picture, engagement statistics etc.

API Pricing (per request): 1 unit

API usage examples

  • Username does not exist:
    -> null returned.
    Cost: 1 unit

  • Username exists:
    -> info returned.
    Cost: 1 unit


Try the API

query Parameters
username
required
string (Username) non-empty
Example: username=daviddobrik

The username to fetch info for.

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/tt/user/info"
params = {
  "username": "daviddobrik",
  "token": "YOUR-TOKEN-HERE"
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{}

User Info From Secuid

Fetch user information and statistics from their secondary user ID. The data returned includes country, language, biography, profile picture, engagement statistics etc.

API Pricing (per request): 1 unit

API usage examples

  • secUid does not exist:
    -> null returned.
    Cost: 1 unit

  • secUid exists:
    -> info returned.
    Cost: 1 unit


Try the API

query Parameters
secUid
required
string (Secuid) non-empty
Example: secUid=MS4wLjABAAAAQ45IcDZIqrknyl0FDjs7xDlcxlaRE7CcBx1ENxYkWK00UpeKTTlCQWKxq6t9QM6b

The secondary user ID to fetch info for.

alternative_method
boolean (Alternative Method)
Default: false

Use an alternative endpoint for fetching the data. If true, the returned JSON contains some additional information compared to the default method.

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/tt/user/info-from-secuid"
params = {
  "secUid": "MS4wLjABAAAAQ45IcDZIqrknyl0FDjs7xDlcxlaRE7CcBx1ENxYkWK00UpeKTTlCQWKxq6t9QM6b",
  "alternative_method": False,
  "token": "YOUR-TOKEN-HERE"
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{}

Post Info

Fetch post information and statistics from URL.

API Pricing (per request): 2 units


Try the API
query Parameters
url
required
string (Url)
Example: url=https://www.tiktok.com/@daviddobrik/video/7165262254722534698

The url of the post containing the username and video ID. You should be able to copy this value directly from the search bar in your browser.

token
required
string (Token) [ 12 .. 24 ] characters
Example: token=YOUR_TOKEN_HERE

Private token assigned to each client to access the APIs.

new_version
boolean (New Version)
Default: false

Set to True to enable an alternate version of the TikTok API that returns only the essential fields, resulting in a faster response.

download_video
boolean (Download Video)
Default: false

When new_version=True, set this parameter to True to have the API include the cookie_download field within the video object, which is required for downloading content via the play or download URLs. This will NOT consume more units.

Responses

Request samples 

import requests

root = "https://ensembledata.com/apis"
endpoint = "/tt/post/info"
params = {
  "url": "https://www.tiktok.com/@daviddobrik/video/7165262254722534698",
  "token": "YOUR-TOKEN-HERE",
  "new_version": False,
  "download_video": False
}

res = requests.get(root+endpoint, params=params)
print(res.json())

Response samples

Content type
application/json
{