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 stats and 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

Trigger a fresh sync of a creator's profile stats and videos from TikTok.

Response

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

DELETE/api/v1/creators/:id

Disconnect a creator. Revokes the app's authorization on TikTok (so the creator must re-grant permissions on reconnect) and deletes the creator and all its synced data.

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