API Reference

Tokyo Data exposes a REST API for querying TikTok audience intelligence data. All endpoints are served from https://tokyodata.com/api.

Authentication

Every request must include an API key in the x-api-key header.

x-api-key: your_api_key_here

Requests without a valid key receive a 401 Unauthorized response.

Endpoints

GET /api/health

Verify the API is running and your key is valid.

Request

curl -X GET https://tokyodata.com/api/health \
  -H "x-api-key: your_api_key_here"

Response

{
  "ok": true,
  "service": "api",
  "endpoint": "/api/health",
  "ts": "2025-12-14T03:22:01.000Z"
}

GET /api/clusters

List all audience clusters with their sizes.

Request

curl -X GET https://tokyodata.com/api/clusters \
  -H "x-api-key: your_api_key_here"

Response

{
  "ok": true,
  "total_clusters": 42,
  "clusters": [
    {
      "cluster_number": 0,
      "cluster_name": "DIY & Lifestyle Creators",
      "size": 18432
    }
  ]
}

Field	Type	Description
cluster_number	number	Unique cluster identifier
cluster_name	string	Human-readable cluster label
size	number	Number of users in this cluster

POST /api/vid2clust

Given TikTok video URLs, return the audience cluster for each video's creator.

Request Body

{
  "urls": [
    "https://www.tiktok.com/@username/video/1234567890"
  ]
}

curl -X POST https://tokyodata.com/api/vid2clust \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.tiktok.com/@username/video/1234567890"]}'

Response

[
  {
    "username": "username",
    "cluster_number": 7,
    "cluster_name": "Comedy & Entertainment"
  }
]

Field	Type	Description
username	string	Parsed from the TikTok URL
cluster_number	number	Cluster the creator belongs to
cluster_name	string	Human-readable cluster label

URLs that can't be parsed are returned in an errors array.

POST /api/clust2vid

Given a cluster ID, return recent videos from creators in that cluster.

Request Body

{
  "cluster_id": 7,
  "num_videos": 10
}

Parameter	Type	Constraints
cluster_id	number	Non-negative integer
num_videos	number	1–30

curl -X POST https://tokyodata.com/api/clust2vid \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"cluster_id": 7, "num_videos": 5}'

Response

{
  "ok": true,
  "cluster_id": 7,
  "requested_videos": 5,
  "returned_videos": 5,
  "videos": [
    {
      "username": "creator_name",
      "video_url": "https://www.tiktok.com/@creator_name/video/123",
      "cluster_number": 7
    }
  ]
}

Returns the most recent video per creator, ordered by recency.

POST /api/vid2querysim

Compute semantic similarity between TikTok creators and natural language queries. Videos and queries are paired by index — videos[i] is compared against queries[i].

Request Body

{
  "videos": [
    "https://www.tiktok.com/@creator1/video/111",
    "https://www.tiktok.com/@creator2/video/222"
  ],
  "queries": [
    "fitness influencer who does meal prep",
    "comedy sketch creator"
  ]
}

Parameter	Type	Constraints
videos	string[]	TikTok video URLs
queries	string[]	Natural language descriptions

Arrays must be the same length.

curl -X POST https://tokyodata.com/api/vid2querysim \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"videos": ["https://www.tiktok.com/@creator/video/123"], "queries": ["cooking tutorials"]}'

Response

{
  "ok": true,
  "results": [
    {
      "video": "https://www.tiktok.com/@creator/video/123",
      "username": "creator",
      "similarity": 0.847
    }
  ]
}

Field	Type	Description
video	string	Original URL from request
username	string	Parsed creator username
similarity	number \| "creator not found"	Cosine similarity (0–1), or indicator if the creator isn't in the dataset

Error Responses

All endpoints return errors in a consistent format:

{
  "ok": false,
  "error": "Description of what went wrong"
}

Status	Meaning
401	Missing or invalid API key
400	Invalid request body or parameters
500	Internal server error