Skip to content
DataSocial

Data API — /v1/data/*

Base URL: https://api.datasocial.ai.

Run a query

Section titled “Run a query”
Terminal window
curl https://api.datasocial.ai/v1/data/sql \
  -H 'content-type: application/json' \
  -d '{"sql": "SELECT username, followers FROM tiktok.creators WHERE country = '\''US'\'' ORDER BY followers DESC LIMIT 3"}'

The response:

{
  "columns": [{ "name": "username", "type": "String" }, { "name": "followers", "type": "UInt32" }],
  "rows": [["khaby.lame", 162984146], ["tiktok", 95878095], ["bellapoarch", 91621886]],
  "row_cap": 1000,
  "capped": false,
  "rows_read": 3776512,
  "bytes_read": 49051288,
  "elapsed_ms": 240
}
  • rows are arrays in the order of columns. 64-bit integers (ids) arrive as strings, because they exceed 2^53.
  • capped is true when the result hit the 1,000-row cap.
  • A failed query answers 400 (bad SQL), 403 (not allowed) or 429 (rate limit), with {"error": "…"}.

Endpoints

Section titled “Endpoints”
Endpoint What it does Status
POST /v1/data/sql Runs one ClickHouse SELECT on the tiktok database and returns the rows. Open, free during launch
GET /v1/tables Every table and column you can query, with live row counts. Open
POST /v1/ask Turns a question in plain English into SQL. The SQL is always returned to you before anything runs. Coming soon

What your SQL can do

Section titled “What your SQL can do”
  • Read-only, on the tiktok database only. See the tables.
  • Never write FINAL: every table is already deduplicated.
  • Settings cannot be changed (SET, SETTINGS … are refused), and FORMAT must be left out: results always come back as JSON.
  • tiktok.creators.email is premium and off during launch: name your columns instead of SELECT * on creators. has_email and email_domain are free.