API Reference

All API requests require an x-api-key header. Get your key from the dashboard.

Authentication

# Add this header to every request

x-api-key: mlk_your_key_here

Base URL

https://metriqlab.dev

TikTok Connect Flow

1. Call POST /api/v1/connect/tiktok with your API key → receive an authUrl

2. Redirect your creator to the authUrl

3. TikTok redirects back to MetriqLab — creator is stored automatically

4. Call GET /api/v1/creators to get the new creator's ID

5. Call POST /api/v1/creators/:id/sync to pull their profile & stats (and /videos/sync for videos)

Endpoints

POST/api/v1/connect/tiktok

Generate a TikTok OAuth URL to connect a creator's account. No request body needed — open the authUrl in a popup or redirect. MetriqLab handles the callback internally.

Response

{
  "success": true,
  "data": {
    "authUrl": "https://www.tiktok.com/v2/auth/authorize/?...",
    "state": "abc123"
  }
}

GET/api/v1/creators

List all creators connected under your API key. Optional query params: ?externalId=xxx (TikTok open_id), ?platform=TIKTOK|INSTAGRAM|YOUTUBE.

Response

{
  "success": true,
  "data": [
    {
      "id": "cmq...",
      "platform": "TIKTOK",
      "username": "Spikewmu",
      "externalId": "...",
      "stats": { "followers": 5618, "likes": 1203, ... }
    }
  ]
}

GET/api/v1/creators/:id/profile

Get a creator's profile and latest synced stats.

Response

{
  "success": true,
  "data": {
    "id": "cmq...",
    "platform": "TIKTOK",
    "username": "Spikewmu",
    "stats": {
      "followers": 5618,
      "following": 838,
      "likes": 1203,
      "videoCount": 11,
      "bio": "...",
      "avatarUrl": "..."
    },
    "connectedAt": "2026-06-13T01:50:23.102Z"
  }
}

GET/api/v1/creators/:id/videos

Get a paginated list of a creator's videos. Use ?limit=20&cursor= for pagination.

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "cmq...",
        "externalId": "...",
        "title": "Video title",
        "views": 12400,
        "likes": 890,
        "comments": 34,
        "shares": 12,
        "duration": 30,
        "publishedAt": "2026-05-01T00:00:00.000Z"
      }
    ],
    "nextCursor": "cmq..."
  }
}

POST/api/v1/creators/:id/sync

Sync a creator's profile and stats from TikTok (fast, costs 1 request). The response includes the freshly synced profile + stats, so you don't need a follow-up call to /profile. Videos are synced separately — see POST /videos/sync.

Response

{
  "success": true,
  "data": {
    "synced": true,
    "creator": {
      "id": "cmq...",
      "platform": "TIKTOK",
      "username": "Spikewmu",
      "externalId": "...",
      "stats": { "followers": 5618, "likes": 1203, ... },
      "connectedAt": "2026-06-13T01:50:23.102Z"
    }
  }
}

POST/api/v1/creators/:id/videos/sync

Pull the creator's videos from TikTok and store them. This is the heaviest operation, so it counts as 10 requests against your monthly quota. Returns the synced videos.

Response

{
  "success": true,
  "data": {
    "synced": true,
    "videosSynced": 11,
    "videos": [
      {
        "id": "cmq...",
        "title": "Video title",
        "views": 12400,
        "likes": 890,
        "publishedAt": "2026-05-01T00:00:00.000Z"
      }
    ]
  }
}

DELETE/api/v1/creators/:id

Disconnect a single creator connection: deletes that creator and all its synced data under your account. If the same TikTok account is connected to other businesses, those connections are unaffected. The shared TikTok authorization is only revoked when this is the creator's last remaining connection across all businesses.

Response

{
  "success": true,
  "data": { "disconnected": true }
}

Error Codes

401MISSING_API_KEYNo x-api-key header provided

401INVALID_API_KEYKey not found or invalid format

401REVOKED_API_KEYKey has been revoked

400NOT_CONNECTEDCreator has no connected account

502SYNC_FAILEDError fetching data from TikTok