# CreatorDB API — LLM-Optimized Documentation

> Single-file reference for the CreatorDB API v3, structured for AI-agent consumption.
> Spec last updated: 2026-07-28 | API version: v3
> Source spec: https://docs.creatordb.app/api-v3/api-v3.yaml

## Quick orientation

- Base URL: `https://apiv3.creatordb.app/`
- Auth header: `api-key: <YOUR_API_KEY>` (contact sales@creatordb.app to obtain)
- Billing: usage is charged to the account that **owns** the key, not the caller. A key issued by a
  teammate or a shared org key spends that account's credits.
- Content type: `application/json`
- Pagination: `offset` + `maxResults` (max 100 per request) on POST search endpoints
- Rate limit: gated by API credit balance; per-call cost is in the Credit Costs appendix
- Timestamps: Unix milliseconds unless noted
- Country codes: ISO 3166-1 alpha-3
- No sandbox: every request hits production and consumes credits
- **Method rule: an endpoint is `POST` if and only if it accepts a `fields` parameter.** All 17
  fractional data endpoints (`profile`, `contact`, `performance`, `audience`, `content-detail`,
  `sponsorship` across YouTube/Instagram/TikTok) take their identifier in the JSON **body**, not
  the query string. `performance-history`, `niches`, `topics`, `subtitles/*`, `usage`, and the
  `sponsor/*` read endpoints remain `GET`. See Part 3 → Fractional calls.

## Agent access paths (Beta)

If you are an AI agent, you may not need to write raw HTTP calls at all. Three ways in, all backed
by the same v3 API and the same credit costs documented below:

| Path | Runs in | Setup |
| --- | --- | --- |
| MCP connector (hosted) | Claude web/desktop/mobile, ChatGPT, Gemini, Cursor, and other MCP clients | In Claude, add the official **CreatorDB MCP** connector from Settings -> Connectors -> Browse connectors. In other clients, add `https://mcp.creatordb.app/mcp`. Authorize with a v3 API key |
| MCP connector (local) | Same clients, self-hosted | Run the open-source server via `npx` — https://github.com/CreatorDB/creatordb-mcp-server |
| Agentic skills | Claude Code | Install `SKILL.md` files into `~/.claude/skills/<skill-name>/` |

- The MCP server accepts **v3 keys only** — older keys are rejected at authorization.
- Health check: `https://mcp.creatordb.app/health` returns `{"status":"ok", ...}`.
- After a CreatorDB release adds tools, MCP clients cache the old tool list. Disconnect and
  reconnect the connector with the same key to pick them up. No new key needed.
- Skills are published for direct fetch at `https://docs.creatordb.app/.well-known/agent-skills/<slug>/SKILL.md`,
  with a machine-readable index at `https://docs.creatordb.app/.well-known/agent-skills/index.json`.

Setup guides:
- MCP connector: https://docs.creatordb.app/mcp-server/setting-up-the-creatordb-mcp-connector.md
- Agentic skills: https://docs.creatordb.app/mcp-server/setting-up-creatordb-agentic-skills.md

## Common response envelope

```json
{
  "data": { /* endpoint-specific */ },
  "creditsUsed": 1,
  "creditsAvailable": 9999,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

`creditsAvailable: -1` means unlimited. On error, `success: false` and `errorCode` is populated.

`creditsUsed` is **not always an integer.** Fractional calls bill per field or per item, so values
such as `0.4`, `1.5`, or `3.04` are normal. Parse it as a float, never as an int.


# Part 2: API reference

## Account

### GET /usage — Get API Usage

Source: https://docs.creatordb.app/api-reference/general-operations/get-api-usage.md
Credits: 1

Retrieve your API usage statistics within the specified date range (maximum 365 days). Defaults to 7 days ago when no start or end dates are provided.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `start` | query | string | no | Start date, represented as a Unix timestamp in milliseconds. Defaults to 7 days ago. |
| `end` | query | string | no | End date, represented as a Unix timestamp in milliseconds. Defaults to current time. |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/usage" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Response — `data` payload**

- `records: array<object { date, requestCount, totalQuotaUsed, … 4 more }>`

  API usage records for the requested date range.

  - `date: string`

    Date in YYYYMMDD format (UTC±0).
  - `requestCount: integer`

    Total number of API requests for this API key.
  - `totalQuotaUsed: number`

    Total credits consumed for this API key.
  - `totalQuotaAdded: number`

    Total credits added by admin custom operations for this API key.
  - `endpoints: object`

    Request count and quota usage per endpoint.
  - `platforms?: object`

    Number of requests per social media platform. Empty when no platform-specific calls were made.
  - `quotaByPlatform?: object`

    API credits consumed per social media platform. Empty when no platform-specific calls were made.
- `count: integer`

  Total number of records returned.
- `key: object { creditLimit, creditsRemaining, active }`

  The calling API key's spendlimit status.

  - `creditLimit: number,null`

    The lifetime credit limit for this API key, in credits. `null` when the key has no limit.
  - `creditsRemaining: number,null`

    Remaining credits this API key can spend before reaching its limit, calculated as credit limit minus cumulative spend. A negative value means cumulative spend has exceeded the limit, and further requests are rejected. `null` when the key has no limit of its own, in which case spending is bounded only by the account's available credits.
  - `active: boolean`

    Whether this API key is currently active.

**Example response**

```json
{
  "data": {
    "records": [
      {
        "date": "20260120",
        "requestCount": 47,
        "totalQuotaUsed": 47,
        "totalQuotaAdded": 12,
        "endpoints": {
          "searchInstagram": {
            "count": 12,
            "quotaUsed": 12,
            "quotaAdded": 0
          },
          "getInstagramProfile": {
            "count": 8,
            "quotaUsed": 8,
            "quotaAdded": 0
          },
          "getYoutubeProfile": {
            "count": 15,
            "quotaUsed": 22,
            "quotaAdded": 0,
            "fractional": {
              "count": 9,
              "quotaUsed": 4
            }
          },
          "custom": {
            "count": 3,
            "quotaUsed": 5,
            "quotaAdded": 12
          }
        },
        "platforms": {
          "instagram": 20,
          "tiktok": 10,
          "youtube": 17
        },
        "quotaByPlatform": {
          "instagram": 20,
          "tiktok": 10,
          "youtube": 17
        }
      }
    ],
    "count": 7,
    "key": {
      "creditLimit": 5000,
      "creditsRemaining": 4975,
      "active": true
    }
  },
  "creditsUsed": 1,
  "creditsAvailable": -1,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

## Natural Language Search

### POST /nls — Search Creators by Prompt

Source: https://docs.creatordb.app/api-reference/ai-search/search-creators-by-prompt.md
Credits: dynamic (token-based)

Search for creators across YouTube, Instagram, and TikTok using natural language descriptions. The AI determines the appropriate platform from your query and converts it into structured search filters. Results are delivered via Server-Sent Events (SSE) streaming.

**Request body**

```json
{
  "description": "Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/nls" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -d '{
    "description": "Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers"
  }'
```

## YouTube

### GET /youtube/subtitles/download — Download Video Subtitles

Source: https://docs.creatordb.app/api-reference/youtube/download-video-subtitles.md
Credits: —

Streams the specified YouTube video's subtitle data as a JSON file download with the filename format `{videoId}-{vssId}.json`. Returns a `content-disposition` attachment. Returns `404` if the video or subtitle ID is not found.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `videoId` | query | string | yes | The unique YouTube video ID (length: 11 characters). |
| `vssId` | query | string | yes | The subtitle language record code (example: `a.en`, `.en`, `.zh-Hant`). |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/youtube/subtitles/download?videoId=icxrUIGoEg8&vssId=.en" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

### POST /youtube/audience — Get Audience Demographics

Source: https://docs.creatordb.app/api-reference/youtube/get-audience-demographics.md
Credits: —

Retrieve audience demographic insights for a specified YouTube creator, including country distribution, gender breakdown, and age composition. This endpoint provides detailed audience analytics to help understand creator reach, evaluate audience alignment, and support data‑driven influencer selection and campaign targeting.<br /><br />Optionally pass `fields` in the request body to return only a subset of demographic fields. You are billed for the fields you request, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#youtube/audience). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
  "uniqueId": "@youtube"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/audience" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA" }'
```

**Response — `data` payload**

- `audienceLocations: array,null`

  Country locations of the audience, sorted by descending share.
- `audienceGender: object,null`

  Gender distribution of the audience.
- `audienceAvgAge: integer,null`

  Average age of the audience, rounded to an integer.
- `audienceAgeBreakdown: array,null`

  Distribution of the audience by age range.

**Example response**

```json
{
  "data": {
    "audienceLocations": [
      {
        "country": "USA",
        "share": 0.7795
      },
      {
        "country": "GBR",
        "share": 0.0716
      },
      "… 1 more items"
    ],
    "audienceGender": {
      "maleRatio": 0.5833,
      "femaleRatio": 0.4167
    },
    "audienceAvgAge": 35,
    "audienceAgeBreakdown": [
      {
        "ageRange": "13-17",
        "share": 0.0328
      },
      {
        "ageRange": "18-24",
        "share": 0.2022
      },
      "… 5 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "fd5e5b27302d80f119671196c628e094",
  "timestamp": 1767924063347,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/contact — Get Contact

Source: https://docs.creatordb.app/api-reference/youtube/get-contact.md
Credits: —

Retrieve the contact information of the specified YouTube creator.<br /><br />Optionally pass `fields` in the request body to return a creator's contact information. The single available field, `emails`, is billed at the full-bundle price. The contact endpoint currently exposes only this one billable field, so fractional calls do not offer any savings yet. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#youtube/contact). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
  "uniqueId": "@youtube"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/contact" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA" }'
```

**Response — `data` payload**

- `emails: array<string>`

  Associated email addresses. Empty if unavailable.

**Example response**

```json
{
  "data": {
    "emails": [
      "contact@mrbeastbusiness.com"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "1565d8d07cc82917f4cc22bd240d1adc",
  "timestamp": 1767934354696,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/content-detail — Get Content Details

Source: https://docs.creatordb.app/api-reference/youtube/get-content-details.md
Credits: —

Retrieve the most recent YouTube videos and shorts of a specified creator, including publish time, video or short description, and engagement metrics.<br /><br />Optionally pass `fields` in the request body to limit how many items each content-detail array returns. Each item returned is billed individually, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-item costs, see [Field and Item Costs](/api-v3/field-and-item-costs#youtube/content-detail). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
  "uniqueId": "@youtube",
  "fields": {
    "recentVideos": 5,
    "recentShorts": 5
  }
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/content-detail" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "fields": { "recentVideos": 5 } }'
```

**Response — `data` payload**

- `recentVideos: array<object { publishTime, contentId, title, … 9 more }>`

  Data of recent YouTube videos.

  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `contentId: string`

    The unique identifier. Represented as follows: `https://www.youtube.com/watch?v={contentId}`
  - `title: string`

    The video title.
  - `description: string`

    The video description, including emojis, mentions, URLs, and line breaks.
  - `length: integer`

    Video length in seconds.
  - `isSponsored: boolean`

    `true` if sponsored.
  - `isMemberOnly: boolean`

    `true` if member-only.
  - `likes: integer`

    Number of likes.
  - `comments: integer`

    Number of comments.
  - `views: integer`

    Number of views.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
  - `hashtags: array<string>`

    Keywords in the video description.
- `recentShorts: array<object { publishTime, contentId, title, … 7 more }>`

  Data of recent YouTube shorts.

  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `contentId: string`

    The unique identifier. Represented as follows: `https://www.youtube.com/shorts/{contentId}`
  - `title: string`

    The shorts title.
  - `description: string`

    The shorts description, including emojis, mentions, URLs, and line breaks.
  - `length: integer`

    Shorts length in seconds.
  - `likes: integer`

    Number of likes.
  - `comments: integer`

    Number of comments.
  - `views: integer`

    Number of views.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place <br /> *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
  - `hashtags: array<string>`

    Keywords in the shorts description.

**Example response**

```json
{
  "data": {
    "recentVideos": [
      {
        "publishTime": 1767816009000,
        "contentId": "QJI0an6irrA",
        "title": "30 Celebrities Fight For $1,000,000!",
        "description": "",
        "length": 2518,
        "isSponsored": false,
        "isMemberOnly": false,
        "likes": 955450,
        "comments": 49482,
        "views": 26424459,
        "engagementRate": 0.03803037178547345,
        "hashtags": []
      },
      {
        "publishTime": 1767793392562,
        "contentId": "mktYW177p6U",
        "title": "Guess the Animal",
        "description": "",
        "length": 0,
        "isSponsored": false,
        "isMemberOnly": false,
        "likes": 1800000,
        "comments": 9252,
        "views": 99117362,
        "engagementRate": 0.01825363350570206,
        "hashtags": []
      },
      "… 16 more items"
    ],
    "recentShorts": [
      {
        "publishTime": 1764090000000,
        "contentId": "AWBsoArakNY",
        "title": "Who Has The Fastest Reaction Time?",
        "description": "",
        "length": 31,
        "likes": 1390397,
        "comments": 7470,
        "views": 60879007,
        "engagementRate": 0.022961396200171267,
        "hashtags": []
      },
      {
        "publishTime": 1763754001000,
        "contentId": "HISfrcjiNPM",
        "title": "I Surprised 50 Make-A-Wish Kids With Disneyland",
        "description": "",
        "length": 29,
        "likes": 785027,
        "comments": 11022,
        "views": 30168415,
        "engagementRate": 0.026386835370701443,
        "hashtags": []
      }
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "f6a08c6e27e6413b8d224eb809c1c3d0",
  "timestamp": 1767923892280,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /youtube/performance-history — Get Performance History

Source: https://docs.creatordb.app/api-reference/youtube/get-performance-history.md
Credits: 3

Retrieve daily performance snapshots for a specified YouTube creator, including upload activity, subscriber growth, engagement metrics, and video performance. Dates are returned as Unix timestamps in milliseconds.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `channelId` | query | string | no | Unique channel ID. Provide exactly one of `channelId` or `uniqueId`. |
| `uniqueId` | query | string | no | YouTube channel handle. Accepts `youtube` or `@youtube` format (the `@` prefix is optional). Provide exactly one of `channelId` or `uniqueId`. |
| `pastDayRange` | query | string | yes | Returns one data point per day over the requested range. For example, `30` returns the past 30 days of daily snapshots. Valid range: `1`-`365`. |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/youtube/performance-history?channelId=UCX6OQ3DkcsbYNE6H8uQQuVA&pastDayRange=7" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Response — `data` payload**

- `histories: array<object { timestamp, totalSubscribers, totalContents, … 2 more }>`

  Historical performance snapshots, each containing metrics and a corresponding Unix timestamp in milliseconds.

  - `timestamp: integer`

    The performance snapshot date, represented as a Unix timestamp in milliseconds.
  - `totalSubscribers: integer`

    Total number of subscribers.
  - `totalContents: integer`

    Total number of videos and shorts.
  - `videosPerformanceAll: object { likes, comments, views, … 2 more }`

    Performance metrics for the last 800 YouTube videos.

    - `likes: object { all, avg, median, … 2 more }`

      Likes statistics for the last 800 YouTube videos.

      - `all: integer`

        Total number of likes across the last 800 YouTube videos.
      - `avg: integer`

        Average likes per video for up to the last 800 videos, rounded to an integer.
      - `median: integer`

        Median number of likes across the last 800 videos.
      - `min: integer`

        Minimum number of likes across the last 800 videos.
      - `max: integer`

        Maximum number of likes across the last 800 videos.
    - `comments: object { all, avg, median, … 2 more }`

      Comments statistics for the last 800 YouTube videos.

      - `all: integer`

        Total number of comments across the last 800 videos.
      - `avg: integer`

        Average comments per video for the last 800 videos, rounded to an integer.
      - `median: integer`

        Median number of comments across the last 800 videos.
      - `min: integer`

        Minimum number of comments across the last 800 YouTube videos.
      - `max: integer`

        Maximum number of comments across the last 800 YouTube videos.
    - `views: object { all, avg, median, … 5 more }`

      Views statistics for the last 800 YouTube videos.

      - `all: integer`

        Total number of views across the last 800 videos.
      - `avg: integer`

        Average views per video for the last 800 videos, rounded to an integer.
      - `median: integer`

        Median number of views across the last 800 videos.
      - `min: integer`

        Minimum number of views across the last 800 videos.
      - `max: integer`

        Maximum number of views across the last 800 videos.
      - `percentile25: integer`

        The 25th percentile (first quartile) of views across the last 800 videos.
      - `percentile75: integer`

        The 75th percentile (third quartile) of views across the last 800 videos.
      - `iqr: integer`

        Interquartile range (IQR) of views, calculated as 25th to 75th percentile, representing the spread of the middle 50%.
    - `length: object { avg }`

      Length statistics for the last 800 YouTube videos.

      - `avg: integer`

        Average video length in seconds, rounded to an integer.
    - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

      Engagement metrics for the last 800 videos.

      - `avgEngagementRate: number`

        Average engagement rate per video, rounded to 4th decimal place <br /> - *Engagement Rate = (Likes + Comments + Views)/Subscribers*.
      - `likesPerSubscriber: number`

        Average likes per subscriber for the last 800 videos, rounded to 4th decimal place.
      - `commentsPerSubscriber: number`

        Average comments per subscriber for the last 800 videos, rounded to 4th decimal place.
      - `viewsPerSubscriber: number`

        Average views per subscriber for the last 800 videos, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance across the last 800 videos.

        - … (depth limit)
  - `shortsPerformanceAll: object { likes, comments, views, … 2 more }`

    Performance metrics for the last 800 YouTube shorts.

    - `likes: object { all, avg, median, … 2 more }`

      Likes statistics for the last 800 YouTube shorts.

      - `all: integer`

        Total number of likes across the last 800 shorts.
      - `avg: integer`

        Average likes per short for the last 800 shorts, rounded to an integer.
      - `median: integer`

        The median number of likes across the last 800 shorts.
      - `min: integer`

        The minimum number of likes across the last 800 shorts.
      - `max: integer`

        The maximum number of likes across the last 800 shorts.
    - `comments: object { all, avg, median, … 2 more }`

      Comments statistics for the last 800 YouTube shorts.

      - `all: integer`

        Total number of comments across the last 800 shorts.
      - `avg: integer`

        Average comments per short for the last 800 shorts, rounded to an integer.
      - `median: integer`

        Median number of comments across the last 800 shorts.
      - `min: integer`

        Minimum number of comments across the last 800 shorts.
      - `max: integer`

        Maximum number of comments across the last 800 shorts.
    - `views: object { all, avg, median, … 5 more }`

      Views statistics for the last 800 shorts.

      - `all: integer`

        Total number of views across the last 800 shorts.
      - `avg: integer`

        Average views per short for the last 800 shorts, rounded to an integer.
      - `median: integer`

        Median number of views across the last 800 shorts.
      - `min: integer`

        Minimum number of views across the last 800 shorts.
      - `max: integer`

        Maximum number of views across the last 800 shorts.
      - `percentile25: integer`

        The 25th percentile (first quartile) of views across the last 800 shorts.
      - `percentile75: integer`

        The 75th percentile (third quartile) of views across the last 800 shorts.
      - `iqr: integer`

        Interquartile range (IQR) of views, calculated as 25th to 75th percentile, representing the spread of the middle 50%.
    - `length: object { avg }`

      Length statistics for the last 800 YouTube shorts.

      - `avg: integer`

        Average shorts length in seconds, rounded to an integer.
    - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

      Engagement metrics for the last 800 shorts.

      - `avgEngagementRate: number`

        Average engagement rate per short, rounded to 4th decimal place. <br /> - *Engagement Rate = (Likes + Comments + Views)/Subscribers*.
      - `likesPerSubscriber: number`

        Average likes per subscriber for the last 800 shorts, rounded to 4th decimal place.
      - `commentsPerSubscriber: number`

        Average comments per subscriber for the last 800 shorts, rounded to 4th decimal place.
      - `viewsPerSubscriber: number`

        Average views per subscriber for the last 800 shorts, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance across the last 800 shorts.

        - … (depth limit)

**Example response**

```json
{
  "data": {
    "histories": [
      {
        "timestamp": 1767837367237,
        "totalSubscribers": 459000000,
        "totalContents": 940,
        "videosPerformanceAll": {
          "likes": {
            "all": 710746666,
            "avg": 7252517,
            "median": 3550000,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 4968208,
            "avg": 50696,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 26294349424,
            "avg": 268309688,
            "median": 192170860,
            "min": 26793336,
            "max": 1601867355
          },
          "engagement": {
            "avgEngagementRate": 0.0267,
            "likesPerSubscriber": 0.0158,
            "commentsPerSubscriber": 0.0001,
            "viewsPerSubscriber": 0.5846,
            "engagementConsistency": {
              "cv": 0.4962,
              "medianVsMean": 0.8586,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        },
        "shortsPerformanceAll": {
          "likes": {
            "all": 1100753505,
            "avg": 11586879,
            "median": 10021835,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 3370220,
            "avg": 35476,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 36964836775,
            "avg": 389103545,
            "median": 361915758,
            "min": 0,
            "max": 0
          },
          "engagement": {
            "avgEngagementRate": 0.0304,
            "likesPerSubscriber": 0.0252,
            "commentsPerSubscriber": 0.0001,
            "viewsPerSubscriber": 0.8477,
            "engagementConsistency": {
              "cv": 0.4424,
              "medianVsMean": 0.9726,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      {
        "timestamp": 1767750967237,
        "totalSubscribers": 459000000,
        "totalContents": 939,
        "videosPerformanceAll": {
          "likes": {
            "all": 711273549,
            "avg": 7332717,
            "median": 3600000,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 4988419,
            "avg": 51427,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 26338437548,
            "avg": 271530284,
            "median": 192581549,
            "min": 29219413,
            "max": 1601867355
          },
          "engagement": {
            "avgEngagementRate": 0.0266,
            "likesPerSubscriber": 0.016,
            "commentsPerSubscriber": 0.0001,
            "viewsPerSubscriber": 0.5916,
            "engagementConsistency": {
              "cv": 0.4985,
              "medianVsMean": 0.8618,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        },
        "shortsPerformanceAll": {
          "likes": {
            "all": 1100070624,
            "avg": 11459069,
            "median": 10010917,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 3346944,
            "avg": 34864,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 36904779936,
            "avg": 384424791,
            "median": 358022029,
            "min": 0,
            "max": 0
          },
          "engagement": {
            "avgEngagementRate": 0.0304,
            "likesPerSubscriber": 0.025,
            "commentsPerSubscriber": 0.0001,
            "viewsPerSubscriber": 0.8375,
            "engagementConsistency": {
              "cv": 0.4403,
              "medianVsMean": 0.952,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      "… 4 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "1b18529129b283dea751c6aac22445d5",
  "timestamp": 1767923767306,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/performance — Get Performance Information

Source: https://docs.creatordb.app/api-reference/youtube/get-performance-information.md
Credits: —

Retrieve advanced performance information of a specified YouTube creator, including upload activity, subscriber growth, engagement metrics, and video performance.<br /><br />Optionally pass `fields` in the request body to return only a subset of performance blocks. Requesting a subset bills fractionally, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#youtube/performance). For how fractional costs work, see [Fractional Costs](/api-v3/fractional-calls).

**Request body**

```json
{
  "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
  "uniqueId": "@youtube",
  "fields": [
    "contentCountByDays",
    "ranking"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/performance" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "fields": ["ranking"] }'
```

**Response — `data` payload**

- `contentCountByDays: object { 7d, 30d, 90d }`

  Number of videos published over different time intervals.

  - `7d: integer`

    Number of videos published in the past 7 days.
  - `30d: integer`

    Number of videos published in the past 30 days.
  - `90d: integer`

    Number of videos published in the past 90 days.
- `ranking: object { totalSubscribers, avgEngagementRate }`

  Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.

  - `totalSubscribers: object { global, country, language }`

    Percentile rank of the total subscriber count.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
  - `avgEngagementRate: object { global, country, language }`

    Percentile rank of the average engagement rate for the last 20 YouTube videos.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
- `videosPerformanceRecent: object { likes, comments, views, … 2 more }`

  Performance metrics of the creator's last 20 YouTube videos.

  - `likes: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of likes across the last 20 YouTube videos.
    - `avg: integer`

      Average likes per video for the last 20 YouTube videos, rounded to an integer.
    - `median: integer`

      Median number of likes across the last 20 YouTube videos.
    - `min: integer`

      Minimum number of likes across the last 20 YouTube videos.
    - `max: integer`

      Maximum number of likes across the last 20 YouTube videos.
  - `comments: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of comments across the last 20 YouTube videos.
    - `avg: integer`

      Average comments per video for last 20 YouTube videos, rounded to an integer.
    - `median: integer`

      Median number of comments across the last 20 YouTube videos.
    - `min: integer`

      Minimum number of comments across the last 20 YouTube videos.
    - `max: integer`

      Maximum number of comments across the last 20 YouTube videos.
  - `views: object { all, avg, median, … 5 more }`

    - `all: integer`

      Total number of views across the last 20 YouTube videos.
    - `avg: integer`

      Average views per video for the last 20 YouTube videos, rounded to an integer.
    - `median: integer`

      Median number of views across the last 20 YouTube videos.
    - `min: integer`

      Minimum number of views across the last 20 YouTube videos.
    - `max: integer`

      Maximum number of views across the last 20 YouTube videos.
    - `percentile25: integer`

      The 25th percentile (first quartile) of views across the last 20 YouTube videos.
    - `percentile75: integer`

      The 75th percentile (third quartile) of views across the last 20 YouTube videos.
    - `iqr: integer`

      Interquartile range (IQR) of views, calculated from the 25th to the 75th percentile, representing the spread of the middle 50%.
  - `length: object { avg }`

    Video length in seconds.

    - `avg: integer`

      Average video length in seconds, rounded to an integer.
  - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

    Engagement performance metrics including engagement rates, per-subscriber statistics, and consistency analysis.

    - `avgEngagementRate: number`

      Average engagement rate per video, rounded to 4th decimal place. <br /> - *Engagement Rate = (Likes + Comments + Views)/ Subscribers*
    - `likesPerSubscriber: number`

      Average likes per subscriber for the last 20 YouTube videos, rounded to 4th decimal place.
    - `commentsPerSubscriber: number`

      Average comments per subscriber for the last 20 YouTube videos, rounded to 4th decimal place.
    - `viewsPerSubscriber: number`

      Average views per subscriber for the last 20 YouTube videos, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance across the last 20 YouTube videos.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/ avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore*weight_cv) + (topBottomScore*weight_topBottom) + (medianVsMeanScore*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - If any of the three indicators is `0`, the `consistencyScore` will be null.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 0 - 50 <br /> - Returns `null` when `consistencyScore` is `null`.
- `shortsPerformanceRecent: object { likes, comments, views, … 2 more }`

  Performance metrics of the creator's last 20 YouTube shorts.

  - `likes: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of likes across the last 20 YouTube shorts.
    - `avg: integer`

      Average likes per short for the last 20 YouTube shorts, rounded to an integer.
    - `median: integer`

      Median number of likes across the last 20 YouTube shorts.
    - `min: integer`

      Minimum number of likes across the last 20 YouTube shorts.
    - `max: integer`

      Maximum number of likes across the last 20 YouTube shorts.
  - `comments: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of comments across the last 20 YouTube shorts.
    - `avg: integer`

      Average comments per short, rounded to an integer.
    - `median: integer`

      Median number of comments across the last 20 YouTube shorts.
    - `min: integer`

      Minimum number of comments across the last 20 YouTube shorts.
    - `max: integer`

      Maximum number of comments across the last 20 YouTube shorts.
  - `views: object { all, avg, median, … 5 more }`

    - `all: integer`

      Total number of views across the last 20 YouTube shorts.
    - `avg: integer`

      Average views per short for the last 20 YouTube shorts, rounded to an integer.
    - `median: integer`

      Median number of views across the last 20 YouTube shorts.
    - `min: integer`

      Minimum number of views across the last 20 YouTube shorts.
    - `max: integer`

      Maximum number of views across the last 20 YouTube shorts.
    - `percentile25: integer`

      The 25th percentile (first quartile) of views across the last 20 YouTube shorts.
    - `percentile75: integer`

      The 75th percentile (third quartile) of views across the last 20 YouTube shorts.
    - `iqr: integer`

      Interquartile range (IQR) of views, calculated as the 25th to 75th percentile, representing the spread of the middle 50%.
  - `length: object { avg }`

    Shorts length statistics in seconds.

    - `avg: integer`

      The average shorts length in seconds, rounded to an integer.
  - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

    Engagement performance metrics of shorts including rates, per-subscriber statistics and consistency analysis.

    - `avgEngagementRate: number`

      Average engagement rate per short, rounded to 4th decimal place. <br /> - *Engagement Rate = (Likes + Comments + Views)/ Subscribers*.
    - `likesPerSubscriber: number`

      Average likes per subscriber for the last 20 YouTube shorts, rounded to 4th decimal place.
    - `commentsPerSubscriber: number`

      Average comments per subscriber for the last 20 YouTube shorts, rounded to 4th decimal place.
    - `viewsPerSubscriber: number`

      Average views per subscriber for the last 20 YouTube shorts, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance across the last 20 YouTube shorts.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore\*weight_cv) + (topBottomScore\*weight_topBottom) + (medianVsMeanScore\*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - If any of the three indicators is `0`, the `consistencyScore` will be `null`.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 0 - 50 <br /> - Returns `null` when `consistencyScore` is `null`.
- `videosPerformanceAll: object { likes, comments, views, … 2 more }`

  Creator's video performance metrics for the last 800 YouTube videos.

  - `likes: object { all, avg, median, … 2 more }`

    Likes statistics for the last 800 YouTube videos.

    - `all: integer`

      Total number of likes across the last 800 YouTube videos.
    - `avg: integer`

      Average likes per video for the last 800 YouTube videos, rounded to an integer.
    - `median: integer`

      Median number of likes across the last 800 YouTube videos.
    - `min: integer`

      Minimum number of likes across the last 800 YouTube videos.
    - `max: integer`

      Maximum number of likes across the last 800 YouTube videos.
  - `comments: object { all, avg, median, … 2 more }`

    Comments statistics for the last 800 YouTube videos.

    - `all: integer`

      Total number of comments across the last 800 YouTube videos.
    - `avg: integer`

      Average comments per video for the last 800 YouTube videos, rounded to an integer.
    - `median: integer`

      Median number of comments across the last 800 YouTube videos.
    - `min: integer`

      Minimum number of comments across the last 800 YouTube videos.
    - `max: integer`

      Maximum number of comments across the last 800 YouTube videos.
  - `views: object { all, avg, median, … 5 more }`

    View statistics for the last 800 YouTube videos.

    - `all: integer`

      Total number of views across the last 800 YouTube videos.
    - `avg: integer`

      Average views per video for the last 800 YouTube videos, rounded to an integer.
    - `median: integer`

      Median number of views across the last 800 YouTube videos.
    - `min: integer`

      Minimum number of views across the last 800 YouTube videos.
    - `max: integer`

      Maximum number of views across the last 800 YouTube videos.
    - `percentile25: integer`

      The 25th percentile (first quartile) of views across the last 800 YouTube videos.
    - `percentile75: integer`

      The 75th percentile (third quartile) of views across the last 800 YouTube videos.
    - `iqr: integer`

      Interquartile range (IQR) of views, calculated as 25th to 75th percentile, representing the spread of the middle 50%.
  - `length: object { avg }`

    Video length statistics for the last 800 YouTube videos.

    - `avg: integer`

      Average video length in seconds, rounded to an integer.
  - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

    Engagement metrics for the last 800 YouTube videos.

    - `avgEngagementRate: number`

      Average engagement rate per video, rounded to 4th decimal place. <br /> - *Engagement Rate = (Likes + Comments + Views)/Subscribers*
    - `likesPerSubscriber: number`

      Average likes per subscriber for the last 800 YouTube videos, rounded to 4th decimal place.
    - `commentsPerSubscriber: number`

      Average comments per subscriber for the last 800 YouTube videos, rounded to 4th decimal place.
    - `viewsPerSubscriber: number`

      Average views per subscriber for the last 800 YouTube videos, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance across the last 800 YouTube videos.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore\*weight_cv) + (topBottomScore\*weight_topBottom) + (medianVsMeanScore\*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - If any of the three indicators is `0`, the `consistencyScore` will be `null`.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 0 - 50 <br /> - Returns `null` when `consistencyScore` is `null`.
- `shortsPerformanceAll: object { likes, comments, views, … 2 more }`

  Performance metrics for the last 800 YouTube shorts.

  - `likes: object { all, avg, median, … 2 more }`

    Likes statistics for the last 800 YouTube shorts.

    - `all: integer`

      Total number of likes across the last 800 YouTube shorts.
    - `avg: integer`

      Average likes per short, for the last 800 YouTube shorts, rounded to an integer.
    - `median: integer`

      Median number of likes across the last 800 YouTube shorts.
    - `min: integer`

      Minimum number of likes across the last 800 YouTube shorts.
    - `max: integer`

      Maximum number of likes across the last 800 YouTube shorts.
  - `comments: object { all, avg, median, … 2 more }`

    Comments statistics for the last 800 YouTube shorts.

    - `all: integer`

      Total number of comments across the last 800 YouTube shorts.
    - `avg: integer`

      Average comments per short for the last 800 YouTube shorts, rounded to an integer.
    - `median: integer`

      Median number of comments across the last 800 YouTube shorts.
    - `min: integer`

      Minimum number of comments across the last 800 YouTube shorts.
    - `max: integer`

      Maximum number of comments across the last 800 YouTube shorts.
  - `views: object { all, avg, median, … 5 more }`

    Views statistics for the last 800 YouTube shorts.

    - `all: integer`

      Total number of views across the last 800 YouTube shorts.
    - `avg: integer`

      Average views per short for the last 800 YouTube shorts, rounded to an integer.
    - `median: integer`

      Median number of views across the last 800 YouTube shorts.
    - `min: integer`

      Minimum number of views across the last 800 YouTube shorts.
    - `max: integer`

      Maximum number of views across the last 800 YouTube shorts.
    - `percentile25: integer`

      The 25th percentile (first quartile) of views across the last 800 YouTube shorts.
    - `percentile75: integer`

      The 75th percentile (third quartile) of views across the last 800 YouTube shorts.
    - `iqr: integer`

      Interquartile range (IQR) of views calculated as 25th to 75th percentile, representing the spread of the middle 50%.
  - `length: object { avg }`

    Length statistics for the last 800 YouTube shorts.

    - `avg: integer`

      Average shorts length in seconds, rounded to an integer.
  - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

    Engagement metrics for the last 800 YouTube shorts.

    - `avgEngagementRate: number`

      The average engagement rate per YouTube short, rounded to 4th decimal place. <br /> - *Engagement Rate = (Likes + Comments + Views)/Subscribers*.
    - `likesPerSubscriber: number`

      Average likes per subscriber for the last 800 YouTube shorts, rounded to 4th decimal place.
    - `commentsPerSubscriber: number`

      Average comments per subscriber for the last 800 YouTube shorts, rounded to 4th decimal place.
    - `viewsPerSubscriber: number`

      Average views per subscriber for the last 800 YouTube shorts, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance across the last 800 YouTube shorts.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore\*weight_cv) + (topBottomScore\*weight_topBottom) + (medianVsMeanScore\*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - If any of the three indicators is `0`, the `consistencyScore` will be `null`.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 0 - 50 <br /> * Returns `null` when `consistencyScore` is `null`.
- `recentVideosGrowth: object { g7, g30, g90 }`

  Growth metrics for recent YouTube videos across 7, 30, and 90-day periods.

  - `g7: object { avgViews, engagementRate }`

    Growth metrics over 7 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g30: object { avgViews, engagementRate }`

    Growth metrics over 30 days.

    - `avgViews: number`

      The growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g90: object { avgViews, engagementRate }`

    Growth metrics over 90 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
- `recentShortsGrowth: object { g7, g30, g90 }`

  Growth metrics for recent shorts across 7, 30, and 90-day periods.

  - `g7: object { avgViews, engagementRate }`

    Growth metrics over 7 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g30: object { avgViews, engagementRate }`

    Growth metrics over 30 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g90: object { avgViews, engagementRate }`

    Growth metrics over 90 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
- `videoPrice: object { cpmLow, cpmRaw, cpmHigh, … 3 more }`

  Estimated video prices, including Cost Per Mille (CPM) and per-video rate ranges.

  - `cpmLow: number`

    Lower bound of the estimated Cost Per Mille (CPM) range.
  - `cpmRaw: number`

    Estimated average Cost Per Mille (CPM).
  - `cpmHigh: number`

    Upper bound of the estimated Cost Per Mille (CPM) range.
  - `priceLow: number`

    Lower bound of the estimated media value for a single piece of content.
  - `priceRaw: number`

    Estimated media value for a single piece of content.
  - `priceHigh: number`

    Upper bound of the estimated media value for a single piece of content.
- `shortsPrice: object { cpmLow, cpmRaw, cpmHigh, … 3 more }`

  Estimated YouTube Shorts prices, including CPM and per-video rate ranges.

  - `cpmLow: number`

    Lower bound of the estimated Cost Per Mille (CPM) range.
  - `cpmRaw: number`

    Estimated average Cost Per Mille (CPM) for the creator.
  - `cpmHigh: number`

    Upper bound of the estimated Cost Per Mille (CPM) range.
  - `priceLow: number`

    Lower bound of the estimated media value for a single piece of content.
  - `priceRaw: number`

    Estimated media value for a single piece of content.
  - `priceHigh: number`

    Upper bound of the estimated media value for a single piece of content.

**Example response**

```json
{
  "data": {
    "contentCountByDays": {
      "7d": 3,
      "30d": 8,
      "90d": 26
    },
    "ranking": {
      "totalSubscribers": {
        "global": 1,
        "country": 1,
        "language": 1
      },
      "avgEngagementRate": {
        "global": 0.5279,
        "country": 0.5036,
        "language": 0.4221
      }
    },
    "videosPerformanceRecent": {
      "likes": {
        "all": 71621680,
        "avg": 3581084,
        "median": 2669037,
        "min": 1300000,
        "max": 22000000
      },
      "comments": {
        "all": 1174720,
        "avg": 58736,
        "median": 53951,
        "min": 8770,
        "max": 115035
      },
      "views": {
        "all": 3050115040,
        "avg": 152505752,
        "median": 131558084,
        "min": 56885878,
        "max": 603517253,
        "percentile25": 104827304,
        "percentile75": 149680016,
        "iqr": 44852712
      },
      "length": {
        "avg": 1167
      },
      "engagement": {
        "avgEngagementRate": 0.0231,
        "likesPerSubscriber": 0.0077,
        "commentsPerSubscriber": 0.0001,
        "viewsPerSubscriber": 0.3259,
        "engagementConsistency": {
          "cv": 0.4606,
          "medianVsMean": 0.856,
          "topBottomRatio": 2.6884,
          "consistencyScore": 53,
          "consistencyLevel": "moderate"
        }
      }
    },
    "shortsPerformanceRecent": {
      "likes": {
        "all": 51069500,
        "avg": 2553475,
        "median": 2059098,
        "min": 463000,
        "max": 6200000
      },
      "comments": {
        "all": 635020,
        "avg": 31751,
        "median": 14155,
        "min": 5115,
        "max": 186830
      },
      "views": {
        "all": 3881469200,
        "avg": 194073460,
        "median": 80108228,
        "min": 12298373,
        "max": 968276492,
        "percentile25": 50286890,
        "percentile75": 201918051,
        "iqr": 151631161
      },
      "length": {
        "avg": 29
      },
      "engagement": {
        "avgEngagementRate": 0.0207,
        "likesPerSubscriber": 0.0055,
        "commentsPerSubscriber": 0.0001,
        "viewsPerSubscriber": 0.4147,
        "engagementConsistency": {
          "cv": 0.3732,
          "medianVsMean": 1.0541,
          "topBottomRatio": 3.6335,
          "consistencyScore": 53,
          "consistencyLevel": "moderate"
        }
      }
    },
    "videosPerformanceAll": {
      "likes": {
        "all": 222423708,
        "avg": 4835298,
        "median": 3400000,
        "min": 1300000,
        "max": 28000000
      },
      "comments": {
        "all": 4020078,
        "avg": 87393,
        "median": 71759,
        "min": 8770,
        "max": 349397
      },
      "views": {
        "all": 8897761232,
        "avg": 193429592,
        "median": 165616724,
        "min": 56885878,
        "max": 603517253,
        "percentile25": 130697086,
        "percentile75": 220213535,
        "iqr": 89516449
      },
      "length": {
        "avg": 1280
      },
      "engagement": {
        "avgEngagementRate": 0.0249,
        "likesPerSubscriber": 0.0103,
        "commentsPerSubscriber": 0.0002,
        "viewsPerSubscriber": 0.4133,
        "engagementConsistency": {
          "cv": 0.5654,
          "medianVsMean": 0.8656,
          "topBottomRatio": 4.6788,
          "consistencyScore": 47,
          "consistencyLevel": "low"
        }
      }
    },
    "shortsPerformanceAll": {
      "likes": {
        "all": 1650228640,
        "avg": 10313929,
        "median": 8150000,
        "min": 461000,
        "max": 57000000
      },
      "comments": {
        "all": 5172480,
        "avg": 32328,
        "median": 17060,
        "min": 2772,
        "max": 822627
      },
      "views": {
        "all": 60515376800,
        "avg": 378221105,
        "median": 338464804,
        "min": 6532098,
        "max": 1692388343,
        "percentile25": 136813142,
        "percentile75": 537217514,
        "iqr": 400404372
      },
      "length": {
        "avg": 31
      },
      "engagement": {
        "avgEngagementRate": 0.0279,
        "likesPerSubscriber": 0.022,
        "commentsPerSubscriber": 0.0001,
        "viewsPerSubscriber": 0.8082,
        "engagementConsistency": {
          "cv": 0.4515,
          "medianVsMean": 0.9376,
          "topBottomRatio": 14.6975,
          "consistencyScore": 41,
          "consistencyLevel": "low"
        }
      }
    },
    "recentVideosGrowth": {
      "g7": {
        "avgViews": 0.0158,
        "engagementRate": -0.0156
      },
      "g30": {
        "avgViews": -0.0063,
        "engagementRate": -0.0189
      },
      "g90": {
        "avgViews": 0.0952,
        "engagementRate": -0.1305
      }
    },
    "recentShortsGrowth": {
      "g7": {
        "avgViews": 0.0342,
        "engagementRate": 0.0002
      },
      "g30": {
        "avgViews": 0.4128,
        "engagementRate": -0.0281
      },
      "g90": {
        "avgViews": 0.2758,
        "engagementRate": -0.2429
      }
    }
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "3d69e43ce36749693badd422e38ccc28",
  "timestamp": 1771887295991,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/profile — Get Profile Information

Source: https://docs.creatordb.app/api-reference/youtube/get-profile-information.md
Credits: —

Retrieve the profile information of a specified YouTube creator, including metadata such as subscriber count, account type, language, hashtags, and more.<br /><br />Optionally pass `fields` in the request body to return only a subset of profile fields. You are billed the sum of the requested fields' costs, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, requests that include a fields parameter return a `400` error (`FractionalCallsNotEnabled`). For per-field pricing, see [Field and Item Costs](/api-v3/field-and-item-costs#youtube/profile). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA",
  "uniqueId": "@youtube",
  "fields": [
    "displayName",
    "country",
    "totalSubscribers"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/profile" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCsTcErHg8oDvUnTzoqsYeNw", "fields": ["displayName", "country"] }'
```

**Response — `data` payload**

- `channelId: string`

  Unique channel ID.
- `uniqueId: string`

  Channel handle.
- `displayName: string`

  Channel display name.
- `categoryBreakdown: array<object { category, share }>`

  Distribution of the creator's content by category.

  - `category: string`
  - `share: number`
- `avatarUrl: string`

  Channel profile picture URL.
- `bio: string`

  The channel biography.
- `isVerified: boolean`

  `true` if the account is verified by YouTube.
- `hasSponsors: boolean`

  `true` if there is sponsored content.
- `hasMemberOnlyContents: boolean`

  `true` if there is member-only content.
- `country: string`

  The country represented in **ISO 3166-1 alpha-3** format. For the country code list, see [here](https://docs.creatordb.app/api-v2/country-code).
- `mainLanguage: string`

  The primary language used in contents, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `languages: array<string>`

  All languages used in contents, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `secondLanguage: string`

  The secondary language used in contents, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `totalContents: integer`

  Total number of videos and shorts.
- `totalSubscribers: integer`

  Total number of subscribers.
- `subscriberGrowth: object { g7, g30, g90 }`

  Subscriber growth metrics over 7, 30, and 90-day periods.

  - `g7: number`

    Subscriber growth over 7 days, rounded to 4th decimal place.
  - `g30: number`

    Subscriber growth over 30 days, rounded to 4th decimal place.
  - `g90: number`

    Subscriber growth over 90 days, rounded to 4th decimal place.
- `hashtags: array<object { name, contentCount }>`

  Hashtags used in content and related statistics.

  - `name: string`

    Keywords used in video captions or descriptions.
  - `contentCount: integer`

    Number of videos and shorts using the hashtag.
- `topics: array<string>`

  Content subcategories generated by CreatorDB's AI model that classifies creators into about 400 dynamic themes based on their content.
- `niches: array<string>`

  Granular subcategories of content topics identified by CreatorDB's AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
- `otherLinks: array<object { title, url }>`

  Linked websites.

  - `title: string`

    The link name.
  - `url: string`

    URL of the social media profile page.
- `lastPublishTime: integer`

  Upload time of the last uploaded content, represented as a Unix timestamp in milliseconds.
- `relatedCreators: array<string>`

  Creators recommended by YouTube, returned as channel IDs.
- `lastDbUpdateTime: integer`

  Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.

**Example response**

```json
{
  "data": {
    "channelId": "UCsTcErHg8oDvUnTzoqsYeNw",
    "uniqueId": "@unboxtherapy",
    "displayName": "Unbox Therapy",
    "categoryBreakdown": [
      {
        "category": "Science & Technology",
        "share": 1
      }
    ],
    "avatarUrl": "https://yt3.googleusercontent.com/ytc/AIdro_mrdFKrYUtuMEqVUWPmtKSzy0weSdlawiMI2VPqP9yq1ks=s900-c-k-c0x00ffffff-no-rj",
    "bio": "Where products get naked.\n\nHere you will find a variety of videos showcasing the coolest products on the planet. From the newest smartphone to surprising gadgets and technology you never knew existed. It's all here on Unbox Therapy.\n\nBusiness / professional inquiries ONLY - jack [at] unboxtherapy.com\n(please don't use YouTube inbox)",
    "isVerified": true,
    "hasSponsors": true,
    "hasMemberOnlyContents": false,
    "country": "",
    "mainLanguage": "eng",
    "languages": [
      "eng",
      ""
    ],
    "secondLanguage": "",
    "totalContents": 2476,
    "totalSubscribers": 24900000,
    "subscriberGrowth": {
      "g7": 0.004,
      "g30": 0.0122,
      "g90": 0.0081
    },
    "hashtags": [
      {
        "name": "#poolcleaner",
        "contentCount": 1
      },
      {
        "name": "#aiper",
        "contentCount": 1
      },
      "… 98 more items"
    ],
    "topics": [
      "id_apple_ScienceTechnology",
      "id_smartphone_ScienceTechnology",
      "… 7 more items"
    ],
    "niches": [
      "id_smartphone_ScienceTechnology",
      "id_gadget_ScienceTechnology",
      "… 8 more items"
    ],
    "otherLinks": [
      {
        "title": "Twitter",
        "url": "https://twitter.com/unboxtherapy"
      },
      {
        "title": "Facebook",
        "url": "http://facebook.com/unboxtherapy"
      },
      "… 2 more items"
    ],
    "lastPublishTime": 1771519500000,
    "relatedCreators": [
      "UCEdjL1kbZ0K8nFu519vE5LQ",
      "UCMiJRAwDNSNzuYeN2uWa0pA",
      "… 186 more items"
    ],
    "videoPrice": {
      "cpmLow": 9,
      "cpmRaw": 13,
      "cpmHigh": 17,
      "priceLow": 13240,
      "priceRaw": 18914,
      "priceHigh": 24588
    },
    "shortsPrice": {
      "cpmLow": 8,
      "cpmRaw": 11,
      "cpmHigh": 14,
      "priceLow": 12655,
      "priceRaw": 18079,
      "priceHigh": 23502
    },
    "lastDbUpdateTime": 1771893695410
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "15a56a8f5462e75e8b12c1baf88d83c7",
  "timestamp": 1772012370616,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/sponsorship — Get Sponsorship Information

Source: https://docs.creatordb.app/api-reference/youtube/get-sponsorship-information.md
Credits: —

Retrieve recent YouTube videos identified as sponsored content for a specific creator, with metadata and engagement insights for influencer marketing analysis.<br /><br />Optionally pass `fields` in the request body to limit how many sponsoring brands are returned. You are billed per brand returned, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-brand costs, see [Field and Item Costs](/api-v3/field-and-item-costs#youtube/sponsorship). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
  "uniqueId": "@youtube",
  "fields": {
    "sponsorList": 5
  }
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/sponsorship" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "fields": { "sponsorList": 5 } }'
```

**Response — `data` payload**

- `sponsorList: array<object { brandName, brandId, brandIgIds, … 2 more }>`

  List of sponsors and their associated branded content.

  - `brandName: string`

    The sponsor name.
  - `brandId: string`

    The official website URL or unique identifier of the sponsor.
  - `brandIgIds: array<string>`

    The Instagram handles of the sponsor.
  - `sponsoredVideos: array<object { publishTime, contentId, title, … 9 more }>`

    Recent sponsored YouTube videos data.

    - `publishTime: integer`

      Publish time, represented as a Unix timestamp in milliseconds.
    - `contentId: string`

      The unique identifier. Represented as follows: `https://www.youtube.com/watch?v={contentId}`
    - `title: string`

      The sponsored video title.
    - `description: string`

      The sponsored video description, including emojis, mentions, URLs, and line breaks.
    - `length: integer`

      Video length in seconds.
    - `isSponsored: boolean`

      `true` if sponsored.
    - `isMemberOnly: boolean`

      `true` if member-only.
    - `likes: integer`

      Number of likes.
    - `comments: integer`

      Number of comments.
    - `views: integer`

      Number of views.
    - `engagementRate: number`

      Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
    - `hashtags: array<string>`

      Keywords used in the video description.
  - `sponsoredVideosPerformance: object { likes, comments, views, … 2 more }`

    Aggregated performance metrics for sponsored YouTube videos broken down by brands.

    - `likes: object { all, avg, median, … 2 more }`

      Likes statistics for sponsored YouTube videos broken down by brands.

      - `all: integer`

        Total number of likes across the last 20 sponsored YouTube videos.
      - `avg: integer`

        Average likes per video for the last 20 sponsored YouTube videos, rounded to an integer.
      - `median: integer`

        Median number of likes across the last 20 sponsored YouTube videos.
      - `min: integer`

        Minimum number of likes across the last 20 sponsored YouTube videos.
      - `max: integer`

        Maximum number of likes across the last 20 sponsored YouTube videos.
    - `comments: object { all, avg, median, … 2 more }`

      Comments statistics for sponsored YouTube videos broken down by brands.

      - `all: integer`

        Total number of comments across the last 20 sponsored YouTube videos.
      - `avg: integer`

        Average comments per video for the last 20 sponsored YouTube videos, rounded to an integer.
      - `median: integer`

        Median number of comments across the last 20 sponsored YouTube videos.
      - `min: integer`

        Minimum number of comments across the last 20 sponsored YouTube videos.
      - `max: integer`

        Maximum number of comments across the last 20 sponsored YouTube videos.
    - `views: object { all, avg, median, … 5 more }`

      View statistics for sponsored YouTube videos broken down by brands.

      - `all: integer`

        Total number of views across the last 20 sponsored YouTube videos.
      - `avg: integer`

        Average views per video for the last 20 sponsored YouTube videos, rounded to an integer.
      - `median: integer`

        Median number of views across the last 20 sponsored YouTube videos.
      - `min: integer`

        Minimum number of views across the last 20 sponsored YouTube videos.
      - `max: integer`

        Maximum number of views across the last 20 sponsored YouTube videos.
      - `percentile25: integer`

        The 25th percentile (first quartile) of views across the last 20 sponsored YouTube videos.
      - `percentile75: integer`

        The 75th percentile (third quartile) of views across the last 20 sponsored YouTube videos.
      - `iqr: integer`

        Interquartile range (IQR) of views, calculated as 25th to 75th percentile, representing the spread of the middle 50%.
    - `length: object { avg }`

      Length statistics for sponsored YouTube videos broken down by brands.

      - `avg: integer`

        The average sponsored video length in seconds, rounded to an integer.
    - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

      Engagement performance metrics for sponsored YouTube videos broken down by brands.

      - `avgEngagementRate: number`

        Average engagement rate per sponsored video, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
      - `likesPerSubscriber: number`

        Average number of likes per subscriber for sponsored videos, rounded to 4th decimal place.
      - `commentsPerSubscriber: number`

        Average number of comments per subscriber for sponsored videos, rounded to 4th decimal place.
      - `viewsPerSubscriber: number`

        Average number of views per subscriber for sponsored videos, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance across sponsored videos broken down by brands.

        - … (depth limit)

**Example response**

```json
{
  "data": {
    "sponsorList": [
      {
        "brandName": "Current",
        "brandId": "current.com",
        "brandIgIds": [
          "current"
        ],
        "sponsoredVideos": [
          {
            "publishTime": 1757779201000,
            "contentId": "4l97aNza_Zc",
            "title": "Survive 30 Days Chained To Your Ex, Win $250,000",
            "description": "",
            "length": 2224,
            "isSponsored": true,
            "isMemberOnly": false,
            "likes": 3747936,
            "comments": 59717,
            "views": 188712721,
            "engagementRate": 0.0202,
            "hashtags": []
          }
        ],
        "sponsoredVideosPerformance": {
          "likes": {
            "all": 3747936,
            "avg": 3747936,
            "median": 3747936,
            "min": 3747936,
            "max": 3747936
          },
          "comments": {
            "all": 59717,
            "avg": 59717,
            "median": 59717,
            "min": 59717,
            "max": 59717
          },
          "views": {
            "all": 188712721,
            "avg": 188712721,
            "median": 188712721,
            "min": 188712721,
            "max": 188712721
          },
          "engagement": {
            "avgEngagementRate": 0.0202,
            "likesPerSubscriber": 0.0082,
            "commentsPerSubscriber": 0.0001,
            "viewsPerSubscriber": 0.4111,
            "engagementConsistency": {
              "cv": 0,
              "medianVsMean": 1,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      {
        "brandName": "Feastables",
        "brandId": "feastables.com",
        "brandIgIds": [
          "feastables"
        ],
        "sponsoredVideos": [
          {
            "publishTime": 1757779201000,
            "contentId": "4l97aNza_Zc",
            "title": "Survive 30 Days Chained To Your Ex, Win $250,000",
            "description": "",
            "length": 2224,
            "isSponsored": true,
            "isMemberOnly": false,
            "likes": 3747936,
            "comments": 59717,
            "views": 188712721,
            "engagementRate": 0.0202,
            "hashtags": []
          },
          {
            "publishTime": 1756934693370,
            "contentId": "_AbFXuGDRTs",
            "title": "$1 vs $1,000,000,000 Nuclear Bunker!",
            "description": "",
            "length": 1038,
            "isSponsored": true,
            "isMemberOnly": false,
            "likes": 2700000,
            "comments": 35478,
            "views": 137386751,
            "engagementRate": 0.0199,
            "hashtags": []
          },
          "… 2 more items"
        ],
        "sponsoredVideosPerformance": {
          "likes": {
            "all": 12947936,
            "avg": 3236984,
            "median": 3250000,
            "min": 2700000,
            "max": 3747936
          },
          "comments": {
            "all": 210248,
            "avg": 52562,
            "median": 57141,
            "min": 35478,
            "max": 60488
          },
          "views": {
            "all": 649472391,
            "avg": 162368098,
            "median": 161686460,
            "min": 137386751,
            "max": 188712721
          },
          "engagement": {
            "avgEngagementRate": 0.0203,
            "likesPerSubscriber": 0.0071,
            "commentsPerSubscriber": 0.0001,
            "viewsPerSubscriber": 0.3537,
            "engagementConsistency": {
              "cv": 0.0532,
              "medianVsMean": 0.9889,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      "… 9 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "46985d83e466fcf19bd7b6a0fb4bd0d3",
  "timestamp": 1767923973919,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /youtube/subtitles/meta — Get Video Subtitles

Source: https://docs.creatordb.app/api-reference/youtube/get-video-subtitles.md
Credits: —

Retrieve available subtitle metadata for a video including `vssId`, `lang`, `langCode`. Returns a 404 error if the video does not exist.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `videoId` | query | string | yes | The unique YouTube video ID (length: 11 characters). |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/youtube/subtitles/meta?videoId=icxrUIGoEg8" \
-H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `videoId: string`

  The video ID.
- `channelId: string`

  The channel ID.
- `availableSubtitles: array<object { vssId, lang, langCode }>`

  List of available subtitle languages with metadata.

  - `vssId: string`

    The subtitle language record code.
  - `lang: string`

    Full language name.
  - `langCode: string`

    The language code in **ISO 639-1** two-letter format.

**Example response**

```json
{
  "data": {
    "videoId": "icxrUIGoEg8",
    "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "availableSubtitles": [
      {
        "vssId": "a.en",
        "lang": "English (Auto-generated)",
        "langCode": "en"
      },
      {
        "vssId": ".en",
        "lang": "English",
        "langCode": "en"
      },
      "… 1 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /youtube/niches — List Niches

Source: https://docs.creatordb.app/api-reference/youtube/list-niches.md
Credits: 1

Retrieve all available YouTube niches with their categories and the number of creators. Niches provide more granular categorization of YouTube creators than topics.

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/youtube/niches" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Example response**

```json
{
  "data": [
    {
      "id": "id_vlog_PeopleBlogs",
      "name": "Vlog",
      "category": "People Blogs",
      "channelCount": 13004
    },
    {
      "id": "id_shorts_PeopleBlogs",
      "name": "Shorts",
      "category": "People Blogs",
      "channelCount": 7709
    },
    "… 8 more items"
  ],
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "aabd94f7ff9e2d0f3fc4e218abd692d0",
  "timestamp": 1772076193778,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /youtube/topics — List Topics

Source: https://docs.creatordb.app/api-reference/youtube/list-topics.md
Credits: 1

Retrieve all available YouTube topics with their categories and creator count. Topics are used for categorizing YouTube creators based on their content themes.

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/youtube/topics" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Example response**

```json
{
  "data": [
    {
      "id": "id_academic_Education",
      "name": "Academic",
      "category": "Education",
      "channelCount": 97
    },
    {
      "id": "id_academichistory_Education",
      "name": "Academic History",
      "category": "Education",
      "channelCount": 92
    },
    "… 7 more items"
  ],
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "0f58e95d22ea888a76166ecf6bb251ef",
  "timestamp": 1772075633067,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/content-search — Search Content

Source: https://docs.creatordb.app/api-reference/youtube/search-content.md
Credits: —

Search for YouTube content (videos, shorts, streams) across all creators in the CreatorDB database using content-level and creator-level filters. Enables discovery of specific content by performance metrics, hashtags, sponsorship status, and more. By default, the `contentList` is sorted by `publishTime` descending (newest first). Custom sorting can be applied using the `sortBy` parameter.

**Request body**

```json
{
  "filters": [
    {
      "filterName": "isSponsored",
      "op": "=",
      "value": true
    },
    {
      "filterName": "views",
      "op": ">",
      "value": 1000000
    },
    {
      "filterName": "publishTime",
      "op": "<",
      "value": 30
    },
    {
      "filterName": "postType",
      "op": "=",
      "value": "video"
    }
  ],
  "sortBy": "views",
  "desc": true,
  "pageSize": 20,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/content-search" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `contentList: array<object { contentId, contentType, title, … 15 more }>`

  Content items matching the search filters.

  - `contentId: string`

    The unique content ID. URL: `https://www.youtube.com/watch?v={contentId}`
  - `contentType: "video" | "shorts" | "stream"`

    Content type: `video`, `shorts`, or `stream`.
  - `title: string`

    The video title.
  - `description: string`

    The video description.
  - `thumbnail: string`

    Thumbnail URL of the video.
  - `url: string`

    Direct URL of the content.
  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `lengthSec: integer`

    Duration of the video in seconds.
  - `isSponsored: boolean`

    `true` if sponsored.
  - `partneredBrands: array<string>`

    Brand IDs (returned as domains) associated with the sponsored content. Empty if the content is not sponsored.
  - `views: integer`

    Number of views.
  - `likes: integer`

    Number of likes.
  - `comments: integer`

    Number of comments.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
  - `hashtags: array<string>`

    Keywords in the video title or description.
  - `language: string`

    Language used in the content, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
  - `category: string`

    Predefined YouTube content category.
  - `creator: object { channelId, displayName, avatarUrl, … 1 more }`

    Creator information for the content.

    - `channelId: string`

      Channel ID.
    - `displayName: string`

      Channel display name.
    - `avatarUrl: string`

      Channel profile picture URL.
    - `totalSubscribers: integer`

      Total subscriber count.
- `totalResults: integer`

  Total number of content items matching the search filters.
- `hasNextPage: boolean`

  `true` if there is a next page of results.
- `nextOffset: integer`

  The offset value for retrieving the next page of results.

**Example response**

```json
{
  "data": {
    "contentList": [
      {
        "contentId": "FbCF_H4ZD64",
        "contentType": "video",
        "title": "I hosted an ADMIN ABUSE on GROW A GARDEN",
        "description": "Thanks @JandelTheGuy play grow a garden here...",
        "thumbnail": "https://i.ytimg.com/vi/FbCF_H4ZD64/hqdefault.jpg",
        "url": "https://www.youtube.com/watch?v=FbCF_H4ZD64",
        "publishTime": 1755273600000,
        "lengthSec": 873,
        "isSponsored": true,
        "partneredBrands": [
          "acer.com"
        ],
        "views": 5009695,
        "likes": 153000,
        "comments": 15182,
        "engagementRate": 0.0336,
        "hashtags": [
          "#VLOG"
        ],
        "language": "eng",
        "category": "Gaming",
        "creator": {
          "channelId": "UCm-X6o81nRsXQTmqpyArkBQ",
          "displayName": "Flamingo",
          "avatarUrl": "https://yt3.googleusercontent.com/7cF22TRiceqQr2Cro_X4uhRVnwCdOa2HXiwdBGPnUEqJDuCyr2CykDfDw2rCWjbjaHEdTMUC=s900-c-k-c0x00ffffff-no-rj",
          "totalSubscribers": 13900000
        }
      }
    ],
    "totalResults": 1250,
    "hasNextPage": true,
    "nextOffset": 20
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/search — Search Creators

Source: https://docs.creatordb.app/api-reference/youtube/search-creators.md
Credits: 1 per 10 filters

Search for YouTube creators using advanced filters such as `displayName`, subscriber count, video performance, and more. Supports fuzzy search, pagination, and multiple filter combinations. At least one filter is required. By default the `creatorList` is sorted by `displayName`. Custom sorting can be applied using the `sortBy` parameter. <br /><br />Optionally pass `fields` to enrich each search result with data from other endpoints. Enrichment is billed per result returned, using each endpoint's own pricing rules. Fractional calls must be enabled on your API key. For details, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "filters": [
    {
      "filterName": "totalSubscribers",
      "op": ">",
      "value": 1000000,
      "isFuzzySearch": true
    }
  ],
  "desc": true,
  "sortBy": "displayName",
  "pageSize": 10,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/search" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{
    "filters":[
    {
      "filterName":
        "totalSubscribers",
        "op":">",
        "value":1000000
    }
    ],
    "pageSize":10,
    "offset":0
    }'
```

**Response — `data` payload**

- `creatorList: array<object { displayName, uniqueId, channelId, … 9 more }>`

  Creator objects matching the search query.

  - `displayName: string`

    Channel display name.
  - `uniqueId: string`

    Unique handle.
  - `channelId: string`

    Unique channel ID.
  - `avatarUrl: string`

    Channel profile picture URL.
  - `totalSubscribers: integer`

    Total number of subscribers.
  - `profile?: object { channelId, uniqueId, displayName, … 20 more }`

    Profile data for this creator. Present only when requested via `fields.profile`.

    - `channelId?: string`

      Unique channel ID.
    - `uniqueId?: string`

      Channel handle.
    - `displayName?: string`

      Channel display name.
    - `categoryBreakdown?: array<object { category, share }>`

      Distribution of the creator's content by category.

      - `category: string`
      - `share: number`
    - `avatarUrl?: string`

      Channel profile picture URL.
    - `bio?: string`

      The channel biography.
    - `isVerified?: boolean`

      `true` if the account is verified by YouTube.
    - `hasSponsors?: boolean`

      `true` if there is sponsored content.
    - `hasMemberOnlyContents?: boolean`

      `true` if there is member-only content.
    - `country?: string`

      The country represented in **ISO 3166-1 alpha-3** format. For the country code list, see [here](https://docs.creatordb.app/api-v2/country-code).
    - `mainLanguage?: string`

      The primary language used in contents, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `languages?: array<string>`

      All languages used in contents, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `secondLanguage?: string`

      The secondary language used in contents, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `totalContents?: integer`

      Total number of videos and shorts.
    - `totalSubscribers?: integer`

      Total number of subscribers.
    - `subscriberGrowth?: object { g7, g30, g90 }`

      Subscriber growth metrics over 7, 30, and 90-day periods.

      - `g7: number`

        Subscriber growth over 7 days, rounded to 4th decimal place.
      - `g30: number`

        Subscriber growth over 30 days, rounded to 4th decimal place.
      - `g90: number`

        Subscriber growth over 90 days, rounded to 4th decimal place.
    - `hashtags?: array<object { name, contentCount }>`

      Hashtags used in content and related statistics.

      - `name: string`

        Keywords used in video captions or descriptions.
      - `contentCount: integer`

        Number of videos and shorts using the hashtag.
    - `topics?: array<string>`

      Content subcategories generated by CreatorDB's AI model that classifies creators into about 400 dynamic themes based on their content.
    - `niches?: array<string>`

      Granular subcategories of content topics identified by CreatorDB's AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
    - `otherLinks?: array<object { title, url }>`

      Linked websites.

      - `title: string`

        The link name.
      - `url: string`

        URL of the social media profile page.
    - `lastPublishTime?: integer`

      Upload time of the last uploaded content, represented as a Unix timestamp in milliseconds.
    - `relatedCreators?: array<string>`

      Creators recommended by YouTube, returned as channel IDs.
    - `lastDbUpdateTime?: integer`

      Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.
  - `performance?: object { contentCountByDays, ranking, videosPerformanceRecent, … 7 more }`

    Performance data for this creator. Present only when requested via `fields.performance`.

    - `contentCountByDays?: object { 7d, 30d, 90d }`

      Number of videos published over different time intervals.

      - `7d: integer`

        Number of videos published in the past 7 days.
      - `30d: integer`

        Number of videos published in the past 30 days.
      - `90d: integer`

        Number of videos published in the past 90 days.
    - `ranking?: object { totalSubscribers, avgEngagementRate }`

      Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.

      - `totalSubscribers: object { global, country, language }`

        Percentile rank of the total subscriber count.

        - … (depth limit)
      - `avgEngagementRate: object { global, country, language }`

        Percentile rank of the average engagement rate for the last 20 YouTube videos.

        - … (depth limit)
    - `videosPerformanceRecent?: object { likes, comments, views, … 2 more }`

      Performance metrics of the creator's last 20 YouTube videos.

      - `likes: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `views: object { all, avg, median, … 5 more }`

        - … (depth limit)
      - `length: object { avg }`

        Video length in seconds.

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

        Engagement performance metrics including engagement rates, per-subscriber statistics, and consistency analysis.

        - … (depth limit)
    - `shortsPerformanceRecent?: object { likes, comments, views, … 2 more }`

      Performance metrics of the creator's last 20 YouTube shorts.

      - `likes: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `views: object { all, avg, median, … 5 more }`

        - … (depth limit)
      - `length: object { avg }`

        Shorts length statistics in seconds.

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

        Engagement performance metrics of shorts including rates, per-subscriber statistics and consistency analysis.

        - … (depth limit)
    - `videosPerformanceAll?: object { likes, comments, views, … 2 more }`

      Creator's video performance metrics for the last 800 YouTube videos.

      - `likes: object { all, avg, median, … 2 more }`

        Likes statistics for the last 800 YouTube videos.

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        Comments statistics for the last 800 YouTube videos.

        - … (depth limit)
      - `views: object { all, avg, median, … 5 more }`

        View statistics for the last 800 YouTube videos.

        - … (depth limit)
      - `length: object { avg }`

        Video length statistics for the last 800 YouTube videos.

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

        Engagement metrics for the last 800 YouTube videos.

        - … (depth limit)
    - `shortsPerformanceAll?: object { likes, comments, views, … 2 more }`

      Performance metrics for the last 800 YouTube shorts.

      - `likes: object { all, avg, median, … 2 more }`

        Likes statistics for the last 800 YouTube shorts.

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        Comments statistics for the last 800 YouTube shorts.

        - … (depth limit)
      - `views: object { all, avg, median, … 5 more }`

        Views statistics for the last 800 YouTube shorts.

        - … (depth limit)
      - `length: object { avg }`

        Length statistics for the last 800 YouTube shorts.

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerSubscriber, commentsPerSubscriber, … 2 more }`

        Engagement metrics for the last 800 YouTube shorts.

        - … (depth limit)
    - `recentVideosGrowth?: object { g7, g30, g90 }`

      Growth metrics for recent YouTube videos across 7, 30, and 90-day periods.

      - `g7: object { avgViews, engagementRate }`

        Growth metrics over 7 days.

        - … (depth limit)
      - `g30: object { avgViews, engagementRate }`

        Growth metrics over 30 days.

        - … (depth limit)
      - `g90: object { avgViews, engagementRate }`

        Growth metrics over 90 days.

        - … (depth limit)
    - `recentShortsGrowth?: object { g7, g30, g90 }`

      Growth metrics for recent shorts across 7, 30, and 90-day periods.

      - `g7: object { avgViews, engagementRate }`

        Growth metrics over 7 days.

        - … (depth limit)
      - `g30: object { avgViews, engagementRate }`

        Growth metrics over 30 days.

        - … (depth limit)
      - `g90: object { avgViews, engagementRate }`

        Growth metrics over 90 days.

        - … (depth limit)
    - `videoPrice?: object { cpmLow, cpmRaw, cpmHigh, … 3 more }`

      Estimated video prices, including Cost Per Mille (CPM) and per-video rate ranges.

      - `cpmLow: number`

        Lower bound of the estimated Cost Per Mille (CPM) range.
      - `cpmRaw: number`

        Estimated average Cost Per Mille (CPM).
      - `cpmHigh: number`

        Upper bound of the estimated Cost Per Mille (CPM) range.
      - `priceLow: number`

        Lower bound of the estimated media value for a single piece of content.
      - `priceRaw: number`

        Estimated media value for a single piece of content.
      - `priceHigh: number`

        Upper bound of the estimated media value for a single piece of content.
    - `shortsPrice?: object { cpmLow, cpmRaw, cpmHigh, … 3 more }`

      Estimated YouTube Shorts prices, including CPM and per-video rate ranges.

      - `cpmLow: number`

        Lower bound of the estimated Cost Per Mille (CPM) range.
      - `cpmRaw: number`

        Estimated average Cost Per Mille (CPM) for the creator.
      - `cpmHigh: number`

        Upper bound of the estimated Cost Per Mille (CPM) range.
      - `priceLow: number`

        Lower bound of the estimated media value for a single piece of content.
      - `priceRaw: number`

        Estimated media value for a single piece of content.
      - `priceHigh: number`

        Upper bound of the estimated media value for a single piece of content.
  - `audience?: object { audienceLocations, audienceGender, audienceAvgAge, … 1 more }`

    Audience demographics for this creator. Present only when requested via `fields.audience`.

    - `audienceLocations?: array,null`

      Country locations of the audience, sorted by descending share.
    - `audienceGender?: object,null`

      Gender distribution of the audience.
    - `audienceAvgAge?: integer,null`

      Average age of the audience, rounded to an integer.
    - `audienceAgeBreakdown?: array,null`

      Distribution of the audience by age range.
  - `contact?: object { emails }`

    Contact information for this creator. Present only when requested via `fields.contact`.

    - `emails?: array<string>`

      Associated email addresses. Empty if unavailable.
  - `content-detail?: object { recentVideos, recentShorts }`

    Recent content published by this creator. Present only when requested via `fields.content-detail`.

    - `recentVideos?: array<object { publishTime, contentId, title, … 9 more }>`

      Data of recent YouTube videos.

      - `publishTime: integer`

        Publish time, represented as a Unix timestamp in milliseconds.
      - `contentId: string`

        The unique identifier. Represented as follows: `https://www.youtube.com/watch?v={contentId}`
      - `title: string`

        The video title.
      - `description: string`

        The video description, including emojis, mentions, URLs, and line breaks.
      - `length: integer`

        Video length in seconds.
      - `isSponsored: boolean`

        `true` if sponsored.
      - `isMemberOnly: boolean`

        `true` if member-only.
      - `likes: integer`

        Number of likes.
      - `comments: integer`

        Number of comments.
      - `views: integer`

        Number of views.
      - `engagementRate: number`

        Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
      - `hashtags: array<string>`

        Keywords in the video description.
    - `recentShorts?: array<object { publishTime, contentId, title, … 7 more }>`

      Data of recent YouTube shorts.

      - `publishTime: integer`

        Publish time, represented as a Unix timestamp in milliseconds.
      - `contentId: string`

        The unique identifier. Represented as follows: `https://www.youtube.com/shorts/{contentId}`
      - `title: string`

        The shorts title.
      - `description: string`

        The shorts description, including emojis, mentions, URLs, and line breaks.
      - `length: integer`

        Shorts length in seconds.
      - `likes: integer`

        Number of likes.
      - `comments: integer`

        Number of comments.
      - `views: integer`

        Number of views.
      - `engagementRate: number`

        Engagement rate, rounded to 4th decimal place <br /> *Engagement Rate &#61; (Likes + Comments + Views) / Subscribers*
      - `hashtags: array<string>`

        Keywords in the shorts description.
  - `sponsorship?: object { sponsorList }`

    Sponsorship data for this creator. Present only when requested via `fields.sponsorship`.

    - `sponsorList?: array<object { brandName, brandId, brandIgIds, … 2 more }>`

      List of sponsors and their associated branded content.

      - `brandName: string`

        The sponsor name.
      - `brandId: string`

        The official website URL or unique identifier of the sponsor.
      - `brandIgIds: array<string>`

        The Instagram handles of the sponsor.
      - `sponsoredVideos: array<object { publishTime, contentId, title, … 9 more }>`

        Recent sponsored YouTube videos data.

        - … (depth limit)
      - `sponsoredVideosPerformance: object { likes, comments, views, … 2 more }`

        Aggregated performance metrics for sponsored YouTube videos broken down by brands.

        - … (depth limit)
  - `performance-history?: object { histories }`

    Daily performance snapshots for this creator. Present only when requested via `fields.performance-history`.

    - `histories: array<object { timestamp, totalSubscribers, totalContents, … 2 more }>`

      Historical performance snapshots, each containing metrics and a corresponding Unix timestamp in milliseconds.

      - `timestamp: integer`

        The performance snapshot date, represented as a Unix timestamp in milliseconds.
      - `totalSubscribers: integer`

        Total number of subscribers.
      - `totalContents: integer`

        Total number of videos and shorts.
      - `videosPerformanceAll: object { likes, comments, views, … 2 more }`

        Performance metrics for the last 800 YouTube videos.

        - … (depth limit)
      - `shortsPerformanceAll: object { likes, comments, views, … 2 more }`

        Performance metrics for the last 800 YouTube shorts.

        - … (depth limit)
- `totalResults: integer`

  Number of results for this search query.
- `hasNextPage: boolean`

  `true` if there is a next page of results.
- `nextOffset: integer`

  The offset value for retrieving the next page of results.

**Example response**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "🪐🌍Gallivud_prod",
        "uniqueId": "@gallivud_prod",
        "channelId": "UCMS8ONu5i0tKTyZ4_lLD1DA",
        "avatarUrl": "https://yt3.googleusercontent.com/geeG3ok-_7PzCBlXDEW8Ro2m0QNl_XRH4AekEVvPqBhgmrFJbn2iKzn06lSnI2GnkybvaJY7=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1400000
      },
      {
        "displayName": "🪐MILENA MARS🪐",
        "uniqueId": "@milenamars",
        "channelId": "UCjTWFYn4s7fzsonX3Jtw_Ig",
        "avatarUrl": "https://yt3.googleusercontent.com/kFfAtp8wQM5wTqRzFn1wiZWdcJ5atGU1u-BnzpadbVFQJBThObAYNZTxsagdHnzW5m79G5A4pg=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 2170000
      },
      "… 8 more items"
    ]
  },
  "hasNextPage": true,
  "nextOffset": 10,
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "f3430ba969f51fc42d633cb4fd00f86d",
  "timestamp": 1767923571340,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /youtube/submitCreators — Submit Creators

Source: https://docs.creatordb.app/api-reference/youtube/submit-creators.md
Credits: —

Submit new YouTube creators to the CreatorDB database for indexing. Accepted creators enter a processing queue and become available via the other YouTube endpoints once first scraped. You are billed per newly accepted creator. Creators already indexed (`done`) or rejected (`rejected`) are not charged. For the current per-creator cost, see [API Credit Usage](/api-v3/api-credit-usage).

**Request body**

```json
{
  "channelIds": [
    "UCm-X6o81nRsXQTmqpyArkBQ",
    "UCX6OQ3DkcsbYNE6H8uQQuVA"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/youtube/submitCreators" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "channelIds": ["UCm-X6o81nRsXQTmqpyArkBQ", "UCX6OQ3DkcsbYNE6H8uQQuVA"] }'
```

**Response — `data` payload**

- `results: array<object { channelId, status, existingChannelId }>`

  Per-creator results, one entry per submitted YouTube channel ID, in the same submission order.

  - `channelId: string`

    The submitted YouTube channel ID.
  - `status: "accepted" | "done" | "rejected"`

    The creator's indexing status. - `accepted`: entered the processing queue (billable).<br/> - `done`: already indexed in the database (not charged). <br/> - `rejected`: invalid or blacklisted (not charged). <br/> For the current per-creator cost, see [API Credit Usage](/api-v3/api-credit-usage).
  - `existingChannelId: string,null`

    Returns the existing CreatorDB identifier when the indexing status is `done`. Otherwise, `null`.

**Example response**

```json
{
  "creditsUsed": 25,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

## Instagram

### POST /instagram/audience — Get Audience Demographics

Source: https://docs.creatordb.app/api-reference/instagram/get-audience-demographics.md
Credits: —

Retrieve audience demographic insights for a specified Instagram creator, including country distribution, gender breakdown, and age composition. This endpoint provides detailed audience analytics to help understand creator reach, evaluate audience alignment, and support data‑driven influencer selection and campaign targeting.<br /><br />Optionally pass `fields` in the request body to return only a subset of demographic fields. You are billed for the fields you request, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#instagram/audience). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "instagram"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/audience" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "cristiano" }'
```

**Response — `data` payload**

- `audienceLocations: array,null`

  Country locations of the audience, sorted by descending share.
- `audienceGender: object,null`

  Gender distribution of the audience.
- `audienceAvgAge: integer,null`

  Average age of the audience, rounded to an integer.
- `audienceAgeBreakdown: array,null`

  Distribution of the audience by age range.

**Example response**

```json
{
  "data": {
    "audienceLocations": [
      {
        "country": "USA",
        "share": 0.7377
      },
      {
        "country": "GBR",
        "share": 0.0493
      },
      "… 1 more items"
    ],
    "audienceGender": {
      "maleRatio": 0.7752,
      "femaleRatio": 0.2248
    },
    "audienceAvgAge": 29,
    "audienceAgeBreakdown": [
      {
        "ageRange": "13-17",
        "share": 0.1059
      },
      {
        "ageRange": "18-24",
        "share": 0.3429
      },
      "… 5 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "85dab7361bacc5adc50b6d9e991d528a",
  "timestamp": 1768486538433,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/contact — Get Contact

Source: https://docs.creatordb.app/api-reference/instagram/get-contact.md
Credits: —

Retrieve the contact information of the specified Instagram creator.<br /><br /> Optionally pass `fields` in the request body to return a creator's contact information. The single available field, `emails`, is billed at the full-bundle price. The contact endpoint currently exposes only this one billable field, so fractional calls do not offer any savings yet. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#instagram/contact). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "instagram"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/contact" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "iamcardib" }'
```

**Response — `data` payload**

- `emails: array<string>`

  Associated email addresses. Empty if unavailable.

**Example response**

```json
{
  "data": {
    "emails": [
      "dwikiryslamyo@gmail.com"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "17ab5d1484d5385d464a6c951dcfe98c",
  "timestamp": 1767933868517,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/content-detail — Get Content Details

Source: https://docs.creatordb.app/api-reference/instagram/get-content-details.md
Credits: —

Retrieve the most recent Instagram image posts and reels of a specific creator, including publish time, post description, and engagement metrics. This endpoint enables users to fetch the latest content details for visual and textual analysis or further content-based operations.<br /><br />Optionally pass `fields` in the request body to limit how many items each content-detail array returns. Each item returned is billed individually, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-item costs, see [Field and Item Costs](/api-v3/field-and-item-costs#instagram/content-detail). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "instagram",
  "fields": {
    "recentImages": 5,
    "recentReels": 5
  }
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/content-detail" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "cristiano", "fields": { "recentReels": 5 } }'
```

**Response — `data` payload**

- `recentImages: array<object { publishTime, contentId, isSponsored, … 9 more }>`

  Data of Instagram image posts.

  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `contentId: string`

    The unique identifier. Represented as follows: `https://www.instagram.com/p/{imageId}`
  - `isSponsored: boolean`

    `true` if sponsored.
  - `description: string`

    The post caption, including emojis and line breaks.
  - `coverImageUrl: string`

    The URL of the first image shown in the Instagram image post.
  - `carouselImageUrls: array<string>`

    URLs of images in the Instagram post.
  - `igGeoTaggedLocation: object,null`

    Tagged location.
  - `likes: number`

    Number of likes.
  - `comments: number`

    Number of comments.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
  - `hashtags: array<string>`

    Keywords used in the post description.
  - `taggedCreators: array<string>`

    Tagged creators.
- `recentReels: array<object { publishTime, contentId, isSponsored, … 10 more }>`

  Data of recent Instagram reels.

  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `contentId: string`

    The unique identifier. Represented as: `https://www.instagram.com/reel/{reelId}`
  - `isSponsored: boolean`

    `true` if sponsored.
  - `description: string`

    The reel caption, including emojis and line breaks.
  - `coverImageUrl: string`

    The cover image URL.
  - `igGeoTaggedLocation: object,null`

    Tagged location.
  - `likes: number`

    Number of likes.
  - `comments: number`

    Number of comments.
  - `views: number`

    Number of views.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
  - `hashtags: array<string>`

    Keywords in the reel description.
  - `taggedCreators: array<string>`

    Tagged creators.
  - `musicInfo: object { id, title, displayArtist }`

    Information about the music used in the reel. Returns an object of empty strings when no music information is available.

    - `id: string`

      Unique identifier of the music track.
    - `title: string`

      Title of the music track.
    - `displayArtist: string`

      Artist name as displayed on Instagram.

**Example response**

```json
{
  "data": {
    "recentImages": [
      {
        "publishTime": 1767901822000,
        "contentId": "DTQxXIujVbM",
        "isSponsored": false,
        "description": "This fight isn’t over. We keep working and we will rise together!",
        "coverImageUrl": "https://www.instagram.com/p/DTQxXIujVbM/media/?size=l",
        "carouselImageUrls": [
          "https://www.instagram.com/p/DTQxXIujVbM/media/?size=l"
        ],
        "igGeoTaggedLocation": null,
        "likes": 801639,
        "comments": 9269,
        "engagementRate": 0.0012,
        "hashtags": [],
        "taggedCreators": []
      },
      {
        "publishTime": 1767707453000,
        "contentId": "DTK-ojYCMS4",
        "isSponsored": false,
        "description": "Focused and ready 🦾",
        "coverImageUrl": "https://www.instagram.com/p/DTK-ojYCMS4/media/?size=l",
        "carouselImageUrls": [
          "https://scontent.cdninstagram.com/v/t51.82787-15/610529583_18671576230056421_2230082919574148745_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=1&ig_cache_key=MzgwNDEyODI4NTYxMzg4OTE5NA%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTgwMS5zZHIuQzMifQ%3D%3D&_nc_ohc=bXT31AbALb8Q7kNvwFGvBZB&_nc_oc=AdmDyEKAXNBiocIcvqOpM5UK3Q8gLqpOgywNptFgA-9do76FFQXuQGQfWglPRBqZaqoy7gDwSz-FBR4CmwxhqkQ_&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent.cdninstagram.com&_nc_gid=f-KrGwIjrGunj1yq0L-4fw&oh=00_AfpMoD070bxVGn4GmBBesDs3_L55Q1KjSkXA7WCvSBinwA&oe=696640B0",
          "https://scontent.cdninstagram.com/v/t51.82787-15/610797258_18671576218056421_6585837875154387424_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=1&ig_cache_key=MzgwNDEyODI4NTYyMjI4MjIwNw%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTc5OS5zZHIuQzMifQ%3D%3D&_nc_ohc=ka7gvRAy2SMQ7kNvwF8FtzO&_nc_oc=AdmHfOMYZd_gJy7Y6ALsi64a5KXh7Er9XKDhXt2C_YN1b_o18fWUDcvXhbBNBn9YbZ2mR87GqAOL5We9pqHbD0Wn&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent.cdninstagram.com&_nc_gid=f-KrGwIjrGunj1yq0L-4fw&oh=00_AfoGGLXuW20-bjfQa-q188vDuu1lyGrmwSQRrpHYeyJADA&oe=6966539A",
          "… 2 more items"
        ],
        "igGeoTaggedLocation": null,
        "likes": 3343821,
        "comments": 31076,
        "engagementRate": 0.005,
        "hashtags": [],
        "taggedCreators": []
      },
      "… 19 more items"
    ],
    "recentReels": [
      {
        "publishTime": 1767025828000,
        "contentId": "DS2pxhLCJTK",
        "isSponsored": false,
        "description": "Game-changers stop time. They are timeless.\n\nCongratulations @djokernole for having in your hands a so deserved first-ever Globe Soccer Awar",
        "coverImageUrl": "https://www.instagram.com/p/DS2pxhLCJTK/media/?size=l",
        "igGeoTaggedLocation": null,
        "likes": 5450766,
        "comments": 59896,
        "views": 89064050,
        "engagementRate": 0.0619,
        "hashtags": [],
        "taggedCreators": []
      },
      {
        "publishTime": 1766660544000,
        "contentId": "DSrxW2EiDsk",
        "isSponsored": false,
        "description": "Esperança que se renova, amor que abraça, família que apoia e luz que guia. Feliz Natal 🎄 ❤️ ✨",
        "coverImageUrl": "https://www.instagram.com/p/DSrxW2EiDsk/media/?size=l",
        "igGeoTaggedLocation": null,
        "likes": 8284332,
        "comments": 80841,
        "views": 146151449,
        "engagementRate": 0.0572,
        "hashtags": [],
        "taggedCreators": [
          "georginagio"
        ]
      },
      "… 10 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "a67a02e9802d17100ab06375bb2cb37c",
  "timestamp": 1767935498559,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /instagram/performance-history — Get Performance History

Source: https://docs.creatordb.app/api-reference/instagram/get-performance-history.md
Credits: 3

Retrieve daily performance snapshots for a specified Instagram creator within a specific period, including upload activity, follower growth, engagement metrics, and post or reel performance. Dates are returned as Unix timestamps in milliseconds.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uniqueId` | query | string | yes | Instagram account ID. Accepts `instagram` or `@instagram` format (@ is stripped automatically). |
| `pastDayRange` | query | string | yes | Returns one data point per day over the requested range. For example, `30` returns the past 30 days of daily snapshots. Valid range: `1`-`365`. |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/instagram/performance-history?uniqueId=cristiano&pastDayRange=30" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Response — `data` payload**

- `histories: array<object { timestamp, totalFollowers, totalFollowing, … 3 more }>`

  Historical performance snapshots, each containing metrics and a corresponding Unix timestamp in milliseconds.

  - `timestamp: integer`

    The performance snapshot date, represented as a Unix timestamp in milliseconds.
  - `totalFollowers: integer`

    Total number of followers.
  - `totalFollowing: integer`

    Total number of accounts followed.
  - `totalContents: integer`

    Total number of posts.
  - `imagesPerformanceRecent: object { likes, comments, engagement }`

    Performance metrics of the image posts for the specified time period.

    - `likes: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of likes.
      - `avg: number`

        Average number of likes per image post, rounded to an integer.
      - `median: number`

        Median number of likes.
      - `min: number`

        Minimum number of likes.
      - `max: number`

        Maximum number of likes.
    - `comments: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of comments.
      - `avg: number`

        Average number of comments per image post, rounded to an integer.
      - `median: number`

        Median number of comments.
      - `min: number`

        Minimum number of comments.
      - `max: number`

        Maximum number of comments.
    - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 1 more }`

      Engagement performance metrics including rates, per-follower statistics, and consistency analysis.

      - `avgEngagementRate: number`

        Average engagement rate per Instagram image post (excluding older pinned image posts), rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments)/ Followers*
      - `likesPerFollower: number`

        Average number of likes per follower, rounded to 4th decimal place.
      - `commentsPerFollower: number`

        Average number of comments per follower, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance.

        - … (depth limit)
  - `reelsPerformanceRecent: object { likes, comments, views, … 1 more }`

    The Instagram reels performance metrics for the specified time period.

    - `likes: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of likes.
      - `avg: number`

        Average number of likes per Instagram reel, rounded to an integer.
      - `median: number`

        Median number of likes.
      - `min: number`

        Minimum number of likes.
      - `max: number`

        Maximum number of likes.
    - `comments: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of comments.
      - `avg: number`

        Average number of comments per Instagram reel, rounded to an integer.
      - `median: number`

        Median number of comments.
      - `min: number`

        Minimum number of comments.
      - `max: number`

        Maximum number of comments.
    - `views: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of views.
      - `avg: number`

        Average number of views per Instagram reel, rounded to an integer.
      - `median: number`

        Median number of views.
      - `min: number`

        Minimum number of views.
      - `max: number`

        Maximum number of views.
    - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

      Engagement performance metrics for Instagram reels.

      - `avgEngagementRate: number`

        Average engagement rate per Instagram reel (excluding older pinned reels), rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
      - `likesPerFollower: number`

        Average number of likes per follower, rounded to 4th decimal place.
      - `commentsPerFollower: number`

        Average number of comments per follower, rounded to 4th decimal place.
      - `viewsPerFollower: number`

        Average number of views per follower, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance across Instagram reels.

        - … (depth limit)

**Example response**

```json
{
  "data": {
    "histories": [
      {
        "timestamp": 1767934923420,
        "totalFollowers": 670701146,
        "totalFollowing": 625,
        "totalContents": 3996,
        "imagesPerformanceRecent": {
          "likes": {
            "all": 129460053,
            "avg": 6813687,
            "median": 4971626,
            "min": 967242,
            "max": 28938447
          },
          "comments": {
            "all": 1454317,
            "avg": 76543,
            "median": 44385,
            "min": 9838,
            "max": 402754
          },
          "engagement": {
            "avgEngagementRate": 0.0103,
            "likesPerFollower": 0.0102,
            "commentsPerFollower": 0.0001,
            "engagementConsistency": {
              "cv": 0.9764,
              "medianVsMean": 0.7283,
              "topBottomRatio": 11.6484,
              "consistencyScore": 37,
              "consistencyLevel": "low"
            }
          }
        },
        "reelsPerformanceRecent": {
          "likes": {
            "all": 53411784,
            "avg": 4450982,
            "median": 1885484,
            "min": 735003,
            "max": 18386191
          },
          "comments": {
            "all": 1200876,
            "avg": 100073,
            "median": 31761,
            "min": 9965,
            "max": 631039
          },
          "views": {
            "all": 1075622364,
            "avg": 89635197,
            "median": 49017380,
            "min": 34884947,
            "max": 250628732
          },
          "engagement": {
            "avgEngagementRate": 0.0401,
            "likesPerFollower": 0.0066,
            "commentsPerFollower": 0.0001,
            "viewsPerFollower": 0.1336,
            "engagementConsistency": {
              "cv": 0.4417,
              "medianVsMean": 0.9014,
              "topBottomRatio": 3.0797,
              "consistencyScore": 56,
              "consistencyLevel": "moderate"
            }
          }
        }
      },
      {
        "timestamp": 1767762123420,
        "totalFollowers": 670646453,
        "totalFollowing": 625,
        "totalContents": 3995,
        "imagesPerformanceRecent": {
          "likes": {
            "all": 132415140,
            "avg": 6620757,
            "median": 4925652,
            "min": 962496,
            "max": 28938630
          },
          "comments": {
            "all": 1474100,
            "avg": 73705,
            "median": 40749,
            "min": 9810,
            "max": 402810
          },
          "engagement": {
            "avgEngagementRate": 0.01,
            "likesPerFollower": 0.0099,
            "commentsPerFollower": 0.0001,
            "engagementConsistency": {
              "cv": 0.9832,
              "medianVsMean": 0.7414,
              "topBottomRatio": 11.6358,
              "consistencyScore": 36,
              "consistencyLevel": "low"
            }
          }
        },
        "reelsPerformanceRecent": {
          "likes": {
            "all": 53196840,
            "avg": 4433070,
            "median": 1883337,
            "min": 730553,
            "max": 18364260
          },
          "comments": {
            "all": 1198032,
            "avg": 99836,
            "median": 31721,
            "min": 9902,
            "max": 630613
          },
          "views": {
            "all": 1071241248,
            "avg": 89270104,
            "median": 48941749,
            "min": 34797482,
            "max": 250347282
          },
          "engagement": {
            "avgEngagementRate": 0.0401,
            "likesPerFollower": 0.0066,
            "commentsPerFollower": 0.0001,
            "viewsPerFollower": 0.1331,
            "engagementConsistency": {
              "cv": 0.4435,
              "medianVsMean": 0.9003,
              "topBottomRatio": 3.0964,
              "consistencyScore": 56,
              "consistencyLevel": "moderate"
            }
          }
        }
      },
      "… 14 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "ea11c06423616d5fe906cc77c5a9697f",
  "timestamp": 1767934923526,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/performance — Get Performance Information

Source: https://docs.creatordb.app/api-reference/instagram/get-performance-information.md
Credits: —

Retrieve advanced performance information of a specified Instagram creator, including post activity, follower growth, engagement metrics, and content performance.<br /><br />Optionally pass `fields` in the request body to return only a subset of performance blocks. Requesting a subset bills fractionally, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#instagram/performance). For how fractional costs work, see [Fractional Costs](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "instagram"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/performance" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "cristiano" }'
```

**Response — `data` payload**

- `contentCountByDays: object { 7d, 30d, 90d }`

  Published Instagram posts over different time intervals.

  - `7d: integer`

    Number of posts published in the past 7 days.
  - `30d: integer`

    Number of posts published in the past 30 days.
  - `90d: integer`

    Number of posts published in the past 90 days.
- `ranking: object { totalFollowers, avgEngagementRate }`

  Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.

  - `totalFollowers: object { global, country, language }`

    Percentile rank of the total follower count.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
  - `avgEngagementRate: object { global, country, language }`

    Percentile rank of the average engagement rate, calculated based on the creator's recent posts.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
- `imagesPerformanceRecent: object { likes, comments, engagement }`

  Performance metrics of the creator's recent Instagram image posts.

  - `likes: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of likes.
    - `avg: number`

      Average number of likes per image post, rounded to an integer.
    - `median: number`

      Median number of likes.
    - `min: number`

      Minimum number of likes.
    - `max: number`

      Maximum number of likes.
  - `comments: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of comments.
    - `avg: number`

      Average number of comments per image post, rounded to an integer.
    - `median: number`

      Median number of comments.
    - `min: number`

      Minimum number of comments.
    - `max: number`

      Maximum number of comments.
  - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 1 more }`

    Engagement performance metrics including rates, per-follower statistics, and consistency analysis.

    - `avgEngagementRate: number`

      Average engagement rate per image post (excluding older pinned image posts), rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments)/ Followers*
    - `likesPerFollower: number`

      Average number of likes per follower, rounded to 4th decimal place.
    - `commentsPerFollower: number`

      Average number of comments per follower, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data*.
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data*.
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore\*weight_cv) + (topBottomScore\*weight_topBottom) + (medianVsMeanScore\*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - Returns `null` when any of the three indicators (`cv`, `medianVsMean`, `topBottomRatio`) is `0`, indicating insufficient data.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 1 - 50 <br /> - Returns `null` when `consistencyScore` is `null`, indicating insufficient data.
- `reelsPerformanceRecent: object { likes, comments, views, … 1 more }`

  Performance metrics of the creator's recent Instagram reels.

  - `likes: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of likes.
    - `avg: number`

      Average number of likes per reel, rounded to an integer.
    - `median: number`

      Median number of likes.
    - `min: number`

      Minimum number of likes.
    - `max: number`

      Maximum number of likes.
  - `comments: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of comments.
    - `avg: number`

      Average number of comments per Instagram reel, rounded to an integer.
    - `median: number`

      Median number of comments.
    - `min: number`

      Minimum number of comments.
    - `max: number`

      Maximum number of comments.
  - `views: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of views.
    - `avg: number`

      Average number of views per reel, rounded to an integer.
    - `median: number`

      Median number of views.
    - `min: number`

      Minimum number of views.
    - `max: number`

      Maximum number of views.
  - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

    Engagement performance metrics of Instagram reels, including standard engagement metrics and views per follower.

    - `avgEngagementRate: number`

      Average engagement rate per reel (excluding older pinned reels), rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments)/ Followers*
    - `likesPerFollower: number`

      Average number of likes per follower, rounded to 4th decimal place.
    - `commentsPerFollower: number`

      Average number of comments per follower, rounded to 4th decimal place.
    - `viewsPerFollower: number`

      Average number of views per follower, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore\*weight_cv) + (topBottomScore\*weight_topBottom) + (medianVsMeanScore\*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - Returns `null` when any of the three indicators (`cv`, `medianVsMean`, `topBottomRatio`) is `0`, indicating insufficient data.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 1 - 50 <br /> - Returns `null` when `consistencyScore` is `null`, indicating insufficient data.
- `recentImagesGrowth: object { g7, g30, g90 }`

  Growth metrics for recent Instagram image posts across 7, 30, and 90-day periods.

  - `g7: object { engagementRate }`

    Growth metrics over 7 days.

    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g30: object { engagementRate }`

    Growth metrics over 30 days.

    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g90: object { engagementRate }`

    Growth metrics over 90 days.

    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
- `recentReelsGrowth: object { g7, g30, g90 }`

  Growth metrics for recent Instagram reels across 7, 30, and 90-day periods.

  - `g7: object { avgViews, engagementRate }`

    Growth metrics over 7 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g30: object { avgViews, engagementRate }`

    Growth metrics over 30 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g90: object { avgViews, engagementRate }`

    Growth metrics over 90 days.

    - `avgViews: number`

      Growth rate of average views, rounded to 4th decimal place.
    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.

**Example response**

```json
{
  "data": {
    "contentCountByDays": {
      "7d": 2,
      "30d": 17,
      "90d": 50
    },
    "ranking": {
      "totalFollowers": {
        "global": 1,
        "country": 1,
        "language": 1
      },
      "avgEngagementRate": {
        "global": 0.3151,
        "country": 0.2419,
        "language": 0.2027
      }
    },
    "imagesPerformanceRecent": {
      "likes": {
        "all": 129460053,
        "avg": 6813687,
        "median": 4971626,
        "min": 967242,
        "max": 28938447
      },
      "comments": {
        "all": 1454317,
        "avg": 76543,
        "median": 44385,
        "min": 9838,
        "max": 402754
      },
      "engagement": {
        "avgEngagementRate": 0.0103,
        "likesPerFollower": 0.0102,
        "commentsPerFollower": 0.0001,
        "engagementConsistency": {
          "cv": 0.9764,
          "medianVsMean": 0.7283,
          "topBottomRatio": 11.6484,
          "consistencyScore": 37,
          "consistencyLevel": "low"
        }
      }
    },
    "reelsPerformanceRecent": {
      "likes": {
        "all": 53411784,
        "avg": 4450982,
        "median": 1885484,
        "min": 735003,
        "max": 18386191
      },
      "comments": {
        "all": 1200876,
        "avg": 100073,
        "median": 31761,
        "min": 9965,
        "max": 631039
      },
      "views": {
        "all": 1075622364,
        "avg": 89635197,
        "median": 49017380,
        "min": 34884947,
        "max": 250628732
      },
      "engagement": {
        "avgEngagementRate": 0.0401,
        "likesPerFollower": 0.0066,
        "commentsPerFollower": 0.0001,
        "viewsPerFollower": 0.1336,
        "engagementConsistency": {
          "cv": 0.4417,
          "medianVsMean": 0.9014,
          "topBottomRatio": 3.0797,
          "consistencyScore": 56,
          "consistencyLevel": "moderate"
        }
      }
    }
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "4dc65ca4b026cc141bbd44adda8f0c55",
  "timestamp": 1767933681199,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/profile — Get Profile Information

Source: https://docs.creatordb.app/api-reference/instagram/get-profile-information.md
Credits: —

Retrieve basic profile information of a specified Instagram creator, including metadata such as follower count, account type, language, hashtags, and more.<br /><br />Optionally pass `fields` in the request body to return only a subset of profile fields. You are billed the sum of the requested fields' costs, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, requests that include a fields parameter return a `400` error (`FractionalCallsNotEnabled`). For per-field pricing, see [Field and Item Costs](/api-v3/field-and-item-costs#instagram/profile). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "instagram",
  "fields": [
    "displayName",
    "country",
    "totalFollowers"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/profile" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "cristiano", "fields": ["displayName", "country"] }'
```

**Response — `data` payload**

- `uniqueId: string`

  The Instagram handle.
- `displayName: string`

  The Instagram account name.
- `category: string`

  The professional account category.
- `avatarUrl: string`

  The profile picture URL.
- `bio: string`

  The profile biography.
- `isBusinessAccount: boolean`

  `true` if it is a business account.
- `isPrivateAccount: boolean`

  `true` if it is a private account.
- `isVerified: boolean`

  `true` if it is verified by Instagram.
- `hasSponsors: boolean`

  `true` if there is sponsored content.
- `country: string`

  The country in **ISO 3166-1 alpha-3** format. For the country code list, see [here](https://docs.creatordb.app/api-v2/country-code).
- `mainLanguage: string`

  The primary language used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `languages: array<string>`

  All languages used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `secondLanguage: string`

  The secondary language used in posts, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `totalContents: integer`

  Total number of image posts and reels.
- `totalFollowers: integer`

  Total number of followers.
- `totalFollowing: integer`

  Total number of accounts followed.
- `subscriberGrowth: object { g7, g30, g90 }`

  Follower growth metrics over 7, 30, and 90-day periods.

  - `g7: number`

    Follower growth over 7 days, rounded to 4th decimal place.
  - `g30: number`

    Follower growth over 30 days, rounded to 4th decimal place.
  - `g90: number`

    Follower growth over 90 days, rounded to 4th decimal place.
- `hashtags: array<object { name, contentCount }>`

  Hashtags in Instagram content and usage statistics.

  - `name: string`

    Keywords used in post captions or descriptions.
  - `contentCount: integer`

    Number of posts using the hashtag.
- `niches: array<string>`

  Granular subcategories of content topics identified by CreatorDB's AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
- `otherLinks: array<object { title, url }>`

  Linked websites.

  - `title: string`

    The link name.
  - `url: string`

    URL of the social media profile page.
- `lastPublishTime: integer`

  Time of the last uploaded content, represented as a Unix timestamp in milliseconds.
- `relatedCreators: array<string>`

  Creators recommended by Instagram.
- `lastDbUpdateTime: integer`

  Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.

**Example response**

```json
{
  "data": {
    "uniqueId": "cristiano",
    "displayName": "Cristiano Ronaldo",
    "category": "Sportsperson",
    "avatarUrl": "https://instagram.ftpe7-4.fna.fbcdn.net/v/t51.2885-19/472007201_1142000150877579_994350541752907763_n.jpg?efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=instagram.ftpe7-4.fna.fbcdn.net&_nc_cat=1&_nc_oc=Q6cZ2QHtqBG6PlzU9JR2BMFQSEMyTG3ySNQrxXzNbDtoV4jaiwe2ReIgdF8V5E0z2ehh8paPfEaFwBlyq2lB943nq7JF&_nc_ohc=OZ2xUG_Zs_MQ7kNvwFipRgY&_nc_gid=KqYk4e7CABSJyh4CSq_QKg&edm=ALGbJPMBAAAA&ccb=7-5&oh=00_Afq_AmZzttY3DR719tqBCbu2zD5NFHQFvobxIE_8cLmUdg&oe=696401DE&_nc_sid=7d3ac5",
    "bio": "SIUUUbscribe to my Youtube Channel!",
    "isBusinessAccount": false,
    "isVerified": true,
    "hasSponsors": false,
    "country": "SAU",
    "mainLanguage": "eng",
    "totalContents": 3995,
    "totalFollowers": 670646453,
    "totalFollowing": 625,
    "hashtags": [
      {
        "name": "#cr7fragances",
        "contentCount": 2
      },
      {
        "name": "#cr7energy",
        "contentCount": 2
      },
      "… 4 more items"
    ],
    "niches": [
      "id_fitness_All",
      "id_lifestyle_All",
      "… 8 more items"
    ],
    "otherLinks": [
      {
        "title": "Perplexity",
        "url": "http://perplexity.ai/ronaldo"
      },
      {
        "title": "WHOOP",
        "url": "http://join.whoop.com/cr7"
      },
      "… 2 more items"
    ],
    "lastPublishTime": 1767707453000,
    "relatedCreators": [
      "erakulis",
      "cr7lifemuseum",
      "… 6 more items"
    ],
    "lastDbUpdateTime": 1767783708328
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "4e143c01006170d2ff95f86e5aaeb400",
  "timestamp": 1767928263490,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/sponsorship — Get Sponsorship Information

Source: https://docs.creatordb.app/api-reference/instagram/get-sponsorship-information.md
Credits: —

Retrieve sponsorship data for a specified Instagram creator, including current and past brand partnerships with performance metrics.<br /><br />Optionally pass `fields` in the request body to limit how many sponsoring brands are returned. You are billed per brand returned, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-brand costs, see [Field and Item Costs](/api-v3/field-and-item-costs#instagram/sponsorship). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "instagram",
  "fields": {
    "sponsorList": 5
  }
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/sponsorship" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "davidbeckham", "fields": { "sponsorList": 5 } }'
```

**Response — `data` payload**

- `sponsorList: array<object { brandName, brandId, brandIgIds, … 4 more }>`

  List of sponsors and their associated branded content.

  - `brandName: string`

    The sponsor name.
  - `brandId: string`

    The official website URL or unique identifier of the sponsor.
  - `brandIgIds: array<string>`

    The Instagram handles of the sponsor.
  - `sponsoredImages: array<object { publishTime, contentId, isSponsored, … 9 more }>`

    Recent sponsored Instagram image post data.

    - `publishTime: integer`

      Publish time, represented as a Unix timestamp in milliseconds.
    - `contentId: string`

      The unique identifier. Represented as follows: `https://www.instagram.com/p/{imageId}`
    - `isSponsored: boolean`

      `true` if sponsored.
    - `description: string`

      The post caption, including emojis and line breaks.
    - `coverImageUrl: string`

      The first image URL in an image post.
    - `carouselImageUrls: array<string>`

      URLs of images in the Instagram post.
    - `igGeoTaggedLocation: object,null`

      Tagged location.
    - `likes: number`

      Number of likes.
    - `comments: number`

      Number of comments.
    - `engagementRate: number`

      Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61; (Likes + Comments)/ Followers*
    - `hashtags: array<string>`

      Keywords used in the post description.
    - `taggedCreators: array<string>`

      Tagged creators.
  - `sponsoredReels: array<object { publishTime, contentId, isSponsored, … 10 more }>`

    Recently sponsored Instagram reels.

    - `publishTime: integer`

      Publish time, represented as a Unix timestamp in milliseconds.
    - `contentId: string`

      The unique identifier. Represented as follows: `https://www.instagram.com/reel/{reelId}`
    - `isSponsored: boolean`

      `true` if sponsored.
    - `description: string`

      The reel caption, including emojis and line breaks.
    - `coverImageUrl: string`

      The cover image URL.
    - `igGeoTaggedLocation: object,null`

      Tagged location.
    - `likes: number`

      Number of likes.
    - `comments: number`

      Number of comments.
    - `views: number`

      Number of views.
    - `engagementRate: number`

      Engagement rate, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
    - `hashtags: array<string>`

      Keywords in the reel description.
    - `taggedCreators: array<string>`

      Tagged creators.
    - `musicInfo: object { id, title, displayArtist }`

      Information about the music used in the reel. Returns an object of empty strings when no music information is available.

      - `id: string`

        Unique identifier of the music track.
      - `title: string`

        Title of the music track.
      - `displayArtist: string`

        Artist name as displayed on Instagram.
  - `sponsoredImagesPerformance: object { likes, comments, engagement }`

    Performance metrics for sponsored Instagram image posts broken down by brands.

    - `likes: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of likes.
      - `avg: number`

        Average number of likes per sponsored image post, rounded to an integer.
      - `median: number`

        Median number of likes.
      - `min: number`

        Minimum number of likes.
      - `max: number`

        Maximum number of likes.
    - `comments: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of comments.
      - `avg: number`

        Average number of comments per sponsored image post, rounded to an integer.
      - `median: number`

        Median number of comments.
      - `min: number`

        Minimum number of comments.
      - `max: number`

        Maximum number of comments.
    - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 1 more }`

      Engagement performance metrics including rates, per-follower statistics and consistency analysis.

      - `avgEngagementRate: number`

        Average engagement rate per image post (excluding older pinned image posts), rounded to 4th decimal place <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
      - `likesPerFollower: number`

        Average number of likes per follower on image posts, rounded to 4th decimal place.
      - `commentsPerFollower: number`

        Average number of comments per follower on image posts, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance of sponsored Instagram image posts broken down by brands.

        - … (depth limit)
  - `sponsoredReelsPerformance: object { likes, comments, views, … 1 more }`

    Performance metrics for sponsored Instagram reels broken down by brands.

    - `likes: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of likes.
      - `avg: number`

        Average number of likes per reel, rounded to an integer.
      - `median: number`

        Median number of likes.
      - `min: number`

        Minimum number of likes.
      - `max: number`

        Maximum number of likes.
    - `comments: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of comments.
      - `avg: number`

        Average number of comments per reel, rounded to an integer.
      - `median: number`

        Median number of comments.
      - `min: number`

        Minimum number of comments.
      - `max: number`

        Maximum number of comments.
    - `views: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of views.
      - `avg: number`

        Average number of views per reel, rounded to an integer.
      - `median: number`

        Median number of views.
      - `min: number`

        Minimum number of views.
      - `max: number`

        Maximum number of views.
    - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

      Engagement performance metrics broken down by brand, including standard engagement metrics and views per follower.

      - `avgEngagementRate: number`

        Average engagement rate per reel (excluding older pinned reels), rounded to 4th decimal place. <br /> *Engagement Rate &#61; (Likes + Comments)/ Followers*
      - `likesPerFollower: number`

        Average number of likes per follower, rounded to 4th decimal place.
      - `commentsPerFollower: number`

        Average number of comments per follower, rounded to 4th decimal place.
      - `viewsPerFollower: number`

        Average number of views per follower, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance of sponsored Instagram reels broken down by brands.

        - … (depth limit)

**Example response**

```json
{
  "data": {
    "sponsorList": [
      {
        "brandName": "",
        "brandId": "",
        "brandIgIds": [
          "boss"
        ],
        "sponsoredImages": [
          {
            "publishTime": 1765812372000,
            "contentId": "DSSgDX6CPDJ",
            "isSponsored": true,
            "description": "Staying cosy in BECKHAM x BOSS ❤️💚 @BOSS",
            "coverImageUrl": "https://www.instagram.com/p/DSSgDX6CPDJ/media/?size=l",
            "carouselImageUrls": [
              "https://scontent-tpe1-1.cdninstagram.com/v/t51.82787-15/586674147_18571109599024953_5473428891274672431_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=100&ig_cache_key=Mzc4ODIzMTE4ODA4Nzg5MjMzMQ%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTkyMC5zZHIuQzMifQ%3D%3D&_nc_ohc=mzrcZSW-0j8Q7kNvwErpPDc&_nc_oc=Admw5RjgGJ4UDaAVuMtABnS5QHxILSOiJVDXCjP69dP_g3--MHS7-6olEt3RMaoat6y9Fasxfhd9N22jT5rEkm72&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-tpe1-1.cdninstagram.com&_nc_gid=8hzpDTpSBTQafx-uH7J2qw&oh=00_Afp8OEFBBTKj7OwDiEIhAOU2BGSX_shgyaxagkFMtAXCFw&oe=69644E35",
              "https://scontent-tpe1-1.cdninstagram.com/v/t51.82787-15/587771643_18571109611024953_6383645157204960335_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=105&ig_cache_key=Mzc4ODIzMTE4ODEwNDYxMjI1NA%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTkyMC5zZHIuQzMifQ%3D%3D&_nc_ohc=g3STp4MqVg4Q7kNvwE-Irnu&_nc_oc=AdlVkw4ZzZXvdbkNryQmCTn9I-8jWPbkfJk5y8xuIMoHlosMgQ4HDsGx_NHRBDck8GNpu4okjdsidTJJjVM2ISde&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-tpe1-1.cdninstagram.com&_nc_gid=8hzpDTpSBTQafx-uH7J2qw&oh=00_AfpxWLVJ4zZOBntDbPVF1oX1psoW_RH3sq6glkzuQ93PgA&oe=69643FF8"
            ],
            "igGeoTaggedLocation": null,
            "likes": 210144,
            "comments": 1383,
            "engagementRate": 0.0024,
            "hashtags": [],
            "taggedCreators": []
          },
          {
            "publishTime": 1763980750000,
            "contentId": "DRb6grcCDRG",
            "isSponsored": true,
            "description": "Ready for Winter in BECKHAM x BOSS… So pleased with the jacket and love the boots 🤎❄️ @BOSS",
            "coverImageUrl": "https://www.instagram.com/p/DRb6grcCDRG/media/?size=l",
            "carouselImageUrls": [
              "https://scontent-tpe1-1.cdninstagram.com/v/t51.82787-15/586676758_18567404911024953_9015316138915494417_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=102&ig_cache_key=Mzc3Mjg2NjQzMzU5NjgzMTkxNQ%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTkyMC5zZHIuQzMifQ%3D%3D&_nc_ohc=mULWBt9Jw94Q7kNvwF8mG4u&_nc_oc=AdnxesyvD-lQSXUgYaltcoWnZ3MVku-N7wx7aSvKjA1fqWXhZ7skbYaY_2ypFVGV63PDLobkwoQGGRJTzieseggu&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-tpe1-1.cdninstagram.com&_nc_gid=8hzpDTpSBTQafx-uH7J2qw&oh=00_AfqhBHX4ryPsQeC0bO8okN8-ALU1q2m5PmogOt8l6CIy6g&oe=69643A29",
              "https://scontent-tpe1-1.cdninstagram.com/v/t51.82787-15/587286274_18567404926024953_3025260660210148405_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=100&ig_cache_key=Mzc3Mjg2NjQzMzkzMjM1MDMxNQ%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTkyMC5zZHIuQzMifQ%3D%3D&_nc_ohc=wwq5b2U4G5sQ7kNvwFQUwj_&_nc_oc=AdmUCP-6GvSUNgFXt-YMhG52UdMwBe2_B-_EZOOlT7bBeCXAGJgvNPxHRJi9D3cpEnJzHvh5ZyA5v9CS1GiBHf1O&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-tpe1-1.cdninstagram.com&_nc_gid=8hzpDTpSBTQafx-uH7J2qw&oh=00_AfpvCpIoJ2OGsJc7EsimTQFGAGPk4JpSK9CjOiC88CZHCA&oe=69644AB6"
            ],
            "igGeoTaggedLocation": null,
            "likes": 231362,
            "comments": 1052,
            "engagementRate": 0.0026,
            "hashtags": [],
            "taggedCreators": []
          },
          "… 2 more items"
        ],
        "sponsoredReels": [
          {
            "publishTime": 1761578139000,
            "contentId": "DQUT0hHCLBI",
            "isSponsored": true,
            "description": "My favourite looks from my BECKHAM x BOSS collection 🙌🏼 All available now at @BOSS 🤎",
            "coverImageUrl": "https://www.instagram.com/p/DQUT0hHCLBI/media/?size=l",
            "igGeoTaggedLocation": null,
            "likes": 268715,
            "comments": 2696,
            "views": 5734200,
            "engagementRate": 0.0473,
            "hashtags": [],
            "taggedCreators": []
          }
        ],
        "sponsoredImagesPerformance": {
          "likes": {
            "all": 1037719,
            "avg": 259430,
            "median": 263069,
            "min": 210144,
            "max": 301438
          },
          "comments": {
            "all": 5665,
            "avg": 1416,
            "median": 1475,
            "min": 1052,
            "max": 1664
          },
          "engagement": {
            "avgEngagementRate": 0.0029,
            "likesPerFollower": 0.0029,
            "commentsPerFollower": 0,
            "engagementConsistency": {
              "cv": 0.152,
              "medianVsMean": 1.0137,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        },
        "sponsoredReelsPerformance": {
          "likes": {
            "all": 268715,
            "avg": 268715,
            "median": 268715,
            "min": 268715,
            "max": 268715
          },
          "comments": {
            "all": 2696,
            "avg": 2696,
            "median": 2696,
            "min": 2696,
            "max": 2696
          },
          "views": {
            "all": 5734200,
            "avg": 5734200,
            "median": 5734200,
            "min": 5734200,
            "max": 5734200
          },
          "engagement": {
            "avgEngagementRate": 0.0031,
            "likesPerFollower": 0.003,
            "commentsPerFollower": 0,
            "viewsPerFollower": 0.0647,
            "engagementConsistency": {
              "cv": 0,
              "medianVsMean": 1,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      {
        "brandName": "",
        "brandId": "",
        "brandIgIds": [
          "adidasfootball"
        ],
        "sponsoredImages": [
          {
            "publishTime": 1764763413000,
            "contentId": "DRzPUpkiFwG",
            "isSponsored": true,
            "description": "Two eras collide… ❤️🩶 @adidasfootball @judebellingham @trent",
            "coverImageUrl": "https://www.instagram.com/p/DRzPUpkiFwG/media/?size=l",
            "carouselImageUrls": [
              "https://scontent-tpe1-1.cdninstagram.com/v/t51.82787-15/587814381_18568838989024953_8953623466680258797_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=105&ig_cache_key=Mzc3OTQzMTg4NzYzOTQ1Nzg0OQ%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTgwMC5zZHIuQzMifQ%3D%3D&_nc_ohc=NFaPRShNPFwQ7kNvwEdbFfO&_nc_oc=Adn2GCS18XHb1Y621p0B0kBaY3S8uFc8_6smURYleFG0vQ02avXoM82MEpZ-xFSj2hpWQUWg5ruDDvqOk4K6Rt75&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-tpe1-1.cdninstagram.com&_nc_gid=8hzpDTpSBTQafx-uH7J2qw&oh=00_AfrrHZ1xOnAKuMUwfnEXY7mCbyn80XW_bQfWf3detFsqlQ&oe=69642D33",
              "https://scontent-tpe1-1.cdninstagram.com/v/t51.82787-15/587293554_18568838998024953_144098021852943215_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=109&ig_cache_key=Mzc3OTQzMTg4NzMyOTA0Mjk5OQ%3D%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6InhwaWRzLjE0NDB4MTgwMC5zZHIuQzMifQ%3D%3D&_nc_ohc=EH37WIcNI4cQ7kNvwEzwVOO&_nc_oc=AdkNUOOH4MVql8WiMQ2_bREG0pRus-6AGPba4t29CRVQhTc7EwFX9DngI6n_jbiYF4_mZ6Fj06Nf81Oin5rDms9X&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=scontent-tpe1-1.cdninstagram.com&_nc_gid=8hzpDTpSBTQafx-uH7J2qw&oh=00_AfoUr3cdoJgn3PyI8TG5s-0XztrM-5ChuPMOCGyriLZ3rw&oe=69643526",
              "… 1 more items"
            ],
            "igGeoTaggedLocation": null,
            "likes": 431701,
            "comments": 1014,
            "engagementRate": 0.0049,
            "hashtags": [],
            "taggedCreators": [
              "trent",
              "judebellingham",
              "… 1 more items"
            ]
          }
        ],
        "sponsoredReels": [],
        "sponsoredImagesPerformance": {
          "likes": {
            "all": 431701,
            "avg": 431701,
            "median": 431701,
            "min": 431701,
            "max": 431701
          },
          "comments": {
            "all": 1014,
            "avg": 1014,
            "median": 1014,
            "min": 1014,
            "max": 1014
          },
          "engagement": {
            "avgEngagementRate": 0.0049,
            "likesPerFollower": 0.0049,
            "commentsPerFollower": 0,
            "engagementConsistency": {
              "cv": 0,
              "medianVsMean": 1,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        },
        "sponsoredReelsPerformance": {
          "likes": {
            "all": 0,
            "avg": 0,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 0,
            "avg": 0,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 0,
            "avg": 0,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "engagement": {
            "avgEngagementRate": 0,
            "likesPerFollower": 0,
            "commentsPerFollower": 0,
            "viewsPerFollower": 0,
            "engagementConsistency": {
              "cv": 0,
              "medianVsMean": 0,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      "… 2 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "b3d9d55bd222f728b6fe053e3047d16f",
  "timestamp": 1767935788415,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /instagram/niches — List Niches

Source: https://docs.creatordb.app/api-reference/instagram/list-niches.md
Credits: 1

Retrieve all available Instagram niche categories and their creator counts. Niches categorize creators by content themes.

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/instagram/niches"\
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Example response**

```json
{
  "data": [
    {
      "id": "id_love_All",
      "name": "love",
      "category": "All",
      "channelCount": 467198
    },
    {
      "id": "id_viral_All",
      "name": "viral",
      "category": "All",
      "channelCount": 364528
    },
    "… 9 more items"
  ],
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "fd1210c8a36844a7fcee90d4e13ace34",
  "timestamp": 1772092953767,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/content-search — Search Content

Source: https://docs.creatordb.app/api-reference/instagram/search-content.md
Credits: —

Search for Instagram content (image posts, reels) across all creators in the CreatorDB database using content-level and creator-level filters. Enables discovery of specific content by performance metrics, hashtags, sponsorship status, and more. By default, the `contentList` is sorted by `publishTime` descending (newest first). Custom sorting can be applied using the `sortBy` parameter.

**Request body**

```json
{
  "filters": [
    {
      "filterName": "hashtag",
      "op": "=",
      "value": "#skincare"
    },
    {
      "filterName": "postType",
      "op": "=",
      "value": "reel"
    },
    {
      "filterName": "likes",
      "op": ">",
      "value": 5000
    },
    {
      "filterName": "publishTime",
      "op": "<",
      "value": 7
    }
  ],
  "sortBy": "likes",
  "desc": true,
  "pageSize": 20,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/content-search" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `contentList: array<object { contentId, contentType, description, … 10 more }>`

  Content items matching the search filters.

  - `contentId: string`

    The unique content ID. <br /> - Image post URL: `https://www.instagram.com/p/{contentId}` <br /> Reel URL: `https://www.instagram.com/reel/{contentId}`
  - `contentType: "reel" | "slideshow" | "video" | null`

    Content type: `reel`, `slideshow`, or `video`. May be `null` for legacy posts that predate `postType` classification.
  - `description: string`

    The content caption.
  - `thumbnail: string`

    Thumbnail or cover image URL of the content.
  - `url: string`

    Direct URL of the content.
  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `isSponsored: boolean`

    `true` if sponsored.
  - `partneredBrands: array<string>`

    Brand IDs (returned as domains) associated with the sponsored content. Empty if the content is not sponsored.
  - `likes: integer`

    Number of likes.
  - `comments: integer`

    Number of comments.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61;(Likes + Comments) / Followers*
  - `hashtags: array<string>`

    Keywords in the content caption.
  - `creator: object { uniqueId, displayName, avatarUrl, … 1 more }`

    Creator information for the content.

    - `uniqueId: string`

      Account handle.
    - `displayName: string`

      Account display name.
    - `avatarUrl: string`

      Account profile picture URL.
    - `totalFollowers: integer`

      Total number of followers.
- `totalResults: integer`

  Total number of content items matching the search filters.
- `hasNextPage: boolean`

  `true` if there is a next page of results.
- `nextOffset: integer`

  The offset value for retrieving the next page of results.

**Example response**

```json
{
  "data": {
    "contentList": [
      {
        "contentId": "DMCkc5CyZdf",
        "contentType": "reel",
        "description": "突然覺得這輩子一定要好好賺錢\n以後都搭商務艙😭😭😭",
        "thumbnail": "https://www.instagram.com/p/DMCkc5CyZdf/media/?size=l",
        "url": "https://www.instagram.com/reel/DMCkc5CyZdf",
        "publishTime": 1752392905000,
        "isSponsored": true,
        "partneredBrands": [
          "acer.com"
        ],
        "likes": 15840,
        "comments": 121,
        "engagementRate": 0.1201,
        "hashtags": [
          "#skincare",
          "#routine"
        ],
        "creator": {
          "uniqueId": "goodalicia",
          "displayName": "愛莉莎莎 Alisasa 🐨",
          "avatarUrl": "https://instagram.ftpe8-4.fna.fbcdn.net/...",
          "totalFollowers": 613344
        }
      }
    ],
    "totalResults": 850,
    "hasNextPage": true,
    "nextOffset": 20
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/search — Search Creators

Source: https://docs.creatordb.app/api-reference/instagram/search-creators.md
Credits: 1 per 10 filters

Search for Instagram creators using advanced filters such as `displayName`, follower count, content performance, and more. Supports fuzzy search, pagination, and multiple filter combinations. At least one filter is required. By default the `creatorList` is sorted by `displayName`. Custom sorting can be applied using the `sortBy` parameter. <br /><br />Optionally pass `fields` to enrich each search result with data from other endpoints. Enrichment is billed per result returned, using each endpoint's own pricing rules. Fractional calls must be enabled on your API key. For details, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "filters": [
    {
      "filterName": "displayName",
      "op": "=",
      "value": "beast",
      "isFuzzySearch": true
    }
  ],
  "desc": true,
  "sortBy": "displayName",
  "pageSize": 10,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/search" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{
    "filters": [
      {"filterName": "country", "op": "=", "value": "USA"},
      {"filterName": "mainLanguage", "op": "=", "value": "eng"},
      {"filterName": "hasSponsors", "op": "=", "value": true},
      {"filterName": "totalFollowers", "op": ">", "value": 50000},
      {"filterName": "totalFollowers", "op": "<", "value": 500000},
      {"filterName": "avgReelsViews", "op": ">", "value": 20000},
      {"filterName": "avgImagesLikes", "op": ">", "value": 1000},
      {"filterName": "totalContents", "op": ">", "value": 50}
    ],
    "sortBy": "avgReelsEngagementRate",
    "desc": true,
    "pageSize": 50,
    "offset": 0
  }'
```

**Response — `data` payload**

- `creatorList: array<object { displayName, uniqueId, avatarUrl, … 8 more }>`

  Creator objects matching the search query.

  - `displayName: string`

    The Instagram account name.
  - `uniqueId: string`

    The Instagram handle.
  - `avatarUrl: string`

    The profile picture URL.
  - `totalFollowers: integer`

    Total number of followers.
  - `profile?: object { uniqueId, displayName, category, … 20 more }`

    Profile data for this creator. Present only when requested via `fields.profile`.

    - `uniqueId?: string`

      The Instagram handle.
    - `displayName?: string`

      The Instagram account name.
    - `category?: string`

      The professional account category.
    - `avatarUrl?: string`

      The profile picture URL.
    - `bio?: string`

      The profile biography.
    - `isBusinessAccount?: boolean`

      `true` if it is a business account.
    - `isPrivateAccount?: boolean`

      `true` if it is a private account.
    - `isVerified?: boolean`

      `true` if it is verified by Instagram.
    - `hasSponsors?: boolean`

      `true` if there is sponsored content.
    - `country?: string`

      The country in **ISO 3166-1 alpha-3** format. For the country code list, see [here](https://docs.creatordb.app/api-v2/country-code).
    - `mainLanguage?: string`

      The primary language used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `languages?: array<string>`

      All languages used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `secondLanguage?: string`

      The secondary language used in posts, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `totalContents?: integer`

      Total number of image posts and reels.
    - `totalFollowers?: integer`

      Total number of followers.
    - `totalFollowing?: integer`

      Total number of accounts followed.
    - `subscriberGrowth?: object { g7, g30, g90 }`

      Follower growth metrics over 7, 30, and 90-day periods.

      - `g7: number`

        Follower growth over 7 days, rounded to 4th decimal place.
      - `g30: number`

        Follower growth over 30 days, rounded to 4th decimal place.
      - `g90: number`

        Follower growth over 90 days, rounded to 4th decimal place.
    - `hashtags?: array<object { name, contentCount }>`

      Hashtags in Instagram content and usage statistics.

      - `name: string`

        Keywords used in post captions or descriptions.
      - `contentCount: integer`

        Number of posts using the hashtag.
    - `niches?: array<string>`

      Granular subcategories of content topics identified by CreatorDB's AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
    - `otherLinks?: array<object { title, url }>`

      Linked websites.

      - `title: string`

        The link name.
      - `url: string`

        URL of the social media profile page.
    - `lastPublishTime?: integer`

      Time of the last uploaded content, represented as a Unix timestamp in milliseconds.
    - `relatedCreators?: array<string>`

      Creators recommended by Instagram.
    - `lastDbUpdateTime?: integer`

      Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.
  - `performance?: object { contentCountByDays, ranking, imagesPerformanceRecent, … 3 more }`

    Performance data for this creator. Present only when requested via `fields.performance`.

    - `contentCountByDays?: object { 7d, 30d, 90d }`

      Published Instagram posts over different time intervals.

      - `7d: integer`

        Number of posts published in the past 7 days.
      - `30d: integer`

        Number of posts published in the past 30 days.
      - `90d: integer`

        Number of posts published in the past 90 days.
    - `ranking?: object { totalFollowers, avgEngagementRate }`

      Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.

      - `totalFollowers: object { global, country, language }`

        Percentile rank of the total follower count.

        - … (depth limit)
      - `avgEngagementRate: object { global, country, language }`

        Percentile rank of the average engagement rate, calculated based on the creator's recent posts.

        - … (depth limit)
    - `imagesPerformanceRecent?: object { likes, comments, engagement }`

      Performance metrics of the creator's recent Instagram image posts.

      - `likes: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 1 more }`

        Engagement performance metrics including rates, per-follower statistics, and consistency analysis.

        - … (depth limit)
    - `reelsPerformanceRecent?: object { likes, comments, views, … 1 more }`

      Performance metrics of the creator's recent Instagram reels.

      - `likes: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `views: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

        Engagement performance metrics of Instagram reels, including standard engagement metrics and views per follower.

        - … (depth limit)
    - `recentImagesGrowth?: object { g7, g30, g90 }`

      Growth metrics for recent Instagram image posts across 7, 30, and 90-day periods.

      - `g7: object { engagementRate }`

        Growth metrics over 7 days.

        - … (depth limit)
      - `g30: object { engagementRate }`

        Growth metrics over 30 days.

        - … (depth limit)
      - `g90: object { engagementRate }`

        Growth metrics over 90 days.

        - … (depth limit)
    - `recentReelsGrowth?: object { g7, g30, g90 }`

      Growth metrics for recent Instagram reels across 7, 30, and 90-day periods.

      - `g7: object { avgViews, engagementRate }`

        Growth metrics over 7 days.

        - … (depth limit)
      - `g30: object { avgViews, engagementRate }`

        Growth metrics over 30 days.

        - … (depth limit)
      - `g90: object { avgViews, engagementRate }`

        Growth metrics over 90 days.

        - … (depth limit)
  - `audience?: object { audienceLocations, audienceGender, audienceAvgAge, … 1 more }`

    Audience demographics for this creator. Present only when requested via `fields.audience`.

    - `audienceLocations?: array,null`

      Country locations of the audience, sorted by descending share.
    - `audienceGender?: object,null`

      Gender distribution of the audience.
    - `audienceAvgAge?: integer,null`

      Average age of the audience, rounded to an integer.
    - `audienceAgeBreakdown?: array,null`

      Distribution of the audience by age range.
  - `contact?: object { emails }`

    Contact information for this creator. Present only when requested via `fields.contact`.

    - `emails?: array<string>`

      Associated email addresses. Empty if unavailable.
  - `content-detail?: object { recentImages, recentReels }`

    Recent content published by this creator. Present only when requested via `fields.content-detail`.

    - `recentImages?: array<object { publishTime, contentId, isSponsored, … 9 more }>`

      Data of Instagram image posts.

      - `publishTime: integer`

        Publish time, represented as a Unix timestamp in milliseconds.
      - `contentId: string`

        The unique identifier. Represented as follows: `https://www.instagram.com/p/{imageId}`
      - `isSponsored: boolean`

        `true` if sponsored.
      - `description: string`

        The post caption, including emojis and line breaks.
      - `coverImageUrl: string`

        The URL of the first image shown in the Instagram image post.
      - `carouselImageUrls: array<string>`

        URLs of images in the Instagram post.
      - `igGeoTaggedLocation: object,null`

        Tagged location.
      - `likes: number`

        Number of likes.
      - `comments: number`

        Number of comments.
      - `engagementRate: number`

        Engagement rate, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
      - `hashtags: array<string>`

        Keywords used in the post description.
      - `taggedCreators: array<string>`

        Tagged creators.
    - `recentReels?: array<object { publishTime, contentId, isSponsored, … 10 more }>`

      Data of recent Instagram reels.

      - `publishTime: integer`

        Publish time, represented as a Unix timestamp in milliseconds.
      - `contentId: string`

        The unique identifier. Represented as: `https://www.instagram.com/reel/{reelId}`
      - `isSponsored: boolean`

        `true` if sponsored.
      - `description: string`

        The reel caption, including emojis and line breaks.
      - `coverImageUrl: string`

        The cover image URL.
      - `igGeoTaggedLocation: object,null`

        Tagged location.
      - `likes: number`

        Number of likes.
      - `comments: number`

        Number of comments.
      - `views: number`

        Number of views.
      - `engagementRate: number`

        Engagement rate, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments) / Followers*
      - `hashtags: array<string>`

        Keywords in the reel description.
      - `taggedCreators: array<string>`

        Tagged creators.
      - `musicInfo: object { id, title, displayArtist }`

        Information about the music used in the reel. Returns an object of empty strings when no music information is available.

        - … (depth limit)
  - `sponsorship?: object { sponsorList }`

    Sponsorship data for this creator. Present only when requested via `fields.sponsorship`.

    - `sponsorList?: array<object { brandName, brandId, brandIgIds, … 4 more }>`

      List of sponsors and their associated branded content.

      - `brandName: string`

        The sponsor name.
      - `brandId: string`

        The official website URL or unique identifier of the sponsor.
      - `brandIgIds: array<string>`

        The Instagram handles of the sponsor.
      - `sponsoredImages: array<object { publishTime, contentId, isSponsored, … 9 more }>`

        Recent sponsored Instagram image post data.

        - … (depth limit)
      - `sponsoredReels: array<object { publishTime, contentId, isSponsored, … 10 more }>`

        Recently sponsored Instagram reels.

        - … (depth limit)
      - `sponsoredImagesPerformance: object { likes, comments, engagement }`

        Performance metrics for sponsored Instagram image posts broken down by brands.

        - … (depth limit)
      - `sponsoredReelsPerformance: object { likes, comments, views, … 1 more }`

        Performance metrics for sponsored Instagram reels broken down by brands.

        - … (depth limit)
  - `performance-history?: object { histories }`

    Daily performance snapshots for this creator. Present only when requested via `fields.performance-history`.

    - `histories: array<object { timestamp, totalFollowers, totalFollowing, … 3 more }>`

      Historical performance snapshots, each containing metrics and a corresponding Unix timestamp in milliseconds.

      - `timestamp: integer`

        The performance snapshot date, represented as a Unix timestamp in milliseconds.
      - `totalFollowers: integer`

        Total number of followers.
      - `totalFollowing: integer`

        Total number of accounts followed.
      - `totalContents: integer`

        Total number of posts.
      - `imagesPerformanceRecent: object { likes, comments, engagement }`

        Performance metrics of the image posts for the specified time period.

        - … (depth limit)
      - `reelsPerformanceRecent: object { likes, comments, views, … 1 more }`

        The Instagram reels performance metrics for the specified time period.

        - … (depth limit)
- `totalResults: integer`

  Number of results for this search query.
- `hasNextPage: boolean`

  `true` if there is a next page of results.
- `nextOffset: integer`

  The offset value for retrieving the next page of results.

**Example response**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "Big Kana 🦍 | B. Jenkins",
        "uniqueId": "ceo.nocap",
        "avatarUrl": "https://instagram.ftpe8-3.fna.fbcdn.net/v/t51.2885-19/337746176_606805874637299_3223478874000522029_n.jpg?efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=instagram.ftpe8-3.fna.fbcdn.net&_nc_cat=111&_nc_oc=Q6cZ2QHmH_4pzuj5dVzej9_fTh3MGW4Q2kVsANXqJGUfeAjY5MjS_I_VwJfMd1bNRB1mxX4b2s9TvqtdAoqTci7whElk&_nc_ohc=g4OQCRIDH6sQ7kNvwG5TE8S&_nc_gid=3EUn-WAXbtoF-FcbafmmZQ&edm=ALGbJPMBAAAA&ccb=7-5&oh=00_Afmz4A2njFAOwYXtPuXfd4pBgi14sdkpg-PZrLmRmTVj1Q&oe=695208DE&_nc_sid=7d3ac5",
        "totalFollowers": 98600
      },
      {
        "displayName": "𝐒.𝐁.𝐅 T͟͞H͟͞E͟͞  𝐆𝐑𝐄𝐀𝐓",
        "uniqueId": "el___grande___",
        "avatarUrl": "https://instagram.ftpe8-1.fna.fbcdn.net/v/t51.2885-19/50907024_241749340050197_5880292939598397440_n.jpg?stp=dst-jpg_s240x240_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4zODcuYzIifQ&_nc_ht=instagram.ftpe8-1.fna.fbcdn.net&_nc_cat=105&_nc_oc=Q6cZ2QHy3nIjou6YQcUcXVGRKXs5-QybiYxqhRD6IqM0FPeGqP8Li-6uENSoHHRkUgvrK8E&_nc_ohc=q0uEiYZ4FkMQ7kNvwEZ9DND&_nc_gid=jl1mlUdmfpG-mAZpC9zZmA&edm=APs17CUBAAAA&ccb=7-5&oh=00_AfnXSWTlmBMkccnLDiRgZieQNK9P7uczwh60eR0Vamc1OA&oe=694C10C7&_nc_sid=10d13b",
        "totalFollowers": 367039
      },
      "… 48 more items"
    ],
    "hasNextPage": true,
    "nextOffset": 50
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "3be1d050c9300ccb2143d7a2b8e9f586",
  "timestamp": 1767931152278,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /instagram/submitCreators — Submit Creators

Source: https://docs.creatordb.app/api-reference/instagram/submit-creators.md
Credits: —

Submit new Instagram creators to the CreatorDB database for indexing. Accepted creators enter a processing queue and become available via the other Instagram endpoints once first scraped. You are billed per newly accepted creator. Creators already indexed (`done`) or rejected (`rejected`) are not charged. For the current per-creator cost, see [API Credit Usage](/api-v3/api-credit-usage).

**Request body**

```json
{
  "uniqueIds": [
    "cristiano",
    "khaby.lame"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/instagram/submitCreators" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueIds": ["cristiano", "khaby.lame"] }'
```

**Response — `data` payload**

- `results: array<object { uniqueId, status, existingUniqueId }>`

  Per-creator results, one entry per submitted Instagram handle, in the same submission order.

  - `uniqueId: string`

    The submitted Instagram handle.
  - `status: "accepted" | "done" | "rejected"`

    The creator's indexing status. - `accepted`: entered the processing queue (billable).<br/> - `done`: already indexed in the database (not charged). <br/> - `rejected`: invalid or blacklisted (not charged). <br/> For the current per-creator cost, see [API Credit Usage](/api-v3/api-credit-usage).
  - `existingUniqueId: string,null`

    Returns the existing CreatorDB identifier when the indexing status is `done`. Otherwise, `null`.

**Example response**

```json
{
  "creditsUsed": 1,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

## TikTok

### POST /tiktok/audience — Get Audience Demographics

Source: https://docs.creatordb.app/api-reference/tiktok/get-audience-demographics.md
Credits: —

Retrieve audience demographic insights for a specified TikTok creator, including country distribution, gender breakdown, and age composition. This endpoint provides detailed audience analytics to help understand creator reach, evaluate audience alignment, and support data‑driven influencer selection and campaign targeting.<br /><br />Optionally pass `fields` in the request body to return only a subset of demographic fields. You are billed for the fields you request, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#tiktok/audience). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "tiktok"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/audience" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "davidbeckham" }'
```

**Response — `data` payload**

- `audienceLocations: array,null`

  Country location of the audience, sorted by descending share.
- `audienceGender: object,null`

  Gender distribution of the audience.
- `audienceAvgAge: integer,null`

  Average age of the audience, rounded to an integer.
- `audienceAgeBreakdown: array,null`

  Distribution of the audience by age range.

**Example response**

```json
{
  "data": {
    "audienceLocations": [
      {
        "country": "USA",
        "share": 0.7795
      },
      {
        "country": "GBR",
        "share": 0.0716
      },
      "… 1 more items"
    ],
    "audienceGender": {
      "maleRatio": 0.5833,
      "femaleRatio": 0.4167
    },
    "audienceAvgAge": 35,
    "audienceAgeBreakdown": [
      {
        "ageRange": "13-17",
        "share": 0.0328
      },
      {
        "ageRange": "18-24",
        "share": 0.2022
      },
      "… 5 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "fd5e5b27302d80f119671196c628e094",
  "timestamp": 1767924063347,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/contact — Get Contact

Source: https://docs.creatordb.app/api-reference/tiktok/get-contact.md
Credits: —

Retrieve the contact information of the specified TikTok creator.<br /><br />Optionally pass `fields` in the request body to return a creator's contact information. The single available field, `emails`, is billed at the full-bundle price. The contact endpoint currently exposes only this one billable field, so fractional calls do not offer any savings yet. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#tiktok/contact). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "tiktok"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/contact" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "kallmekris" }'
```

**Response — `data` payload**

- `emails: array<string>`

  Associated email addresses. Empty if unavailable.

**Example response**

```json
{
  "data": {
    "emails": [
      "teamkriscollins@gersh.com"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "626ec5ec515aa1037668e84a959eeaaf",
  "timestamp": 1767939397696,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/content-detail — Get Content Details

Source: https://docs.creatordb.app/api-reference/tiktok/get-content-details.md
Credits: —

Retrieve the most recent TikTok videos information of a specified creator, including publish time, video description, and engagement metrics.<br /><br />Optionally pass `fields` in the request body to limit how many items each content-detail array returns. Each item returned is billed individually, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-item costs, see [Field and Item Costs](/api-v3/field-and-item-costs#tiktok/content-detail). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "tiktok",
  "fields": {
    "recentVideos": 5
  }
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/content-detail" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "kallmekris", "fields": { "recentVideos": 5 } }'
```

**Response — `data` payload**

- `recentVideos: array<object { publishTime, contentId, description, … 14 more }>`

  Data of recent TikTok videos.

  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `contentId: string`

    The unique identifier. Represented as follows: `https://www.tiktok.com/@{uniqueId}/video/{contentId}`
  - `description: string`

    The video caption, including emojis, hashtags, and line breaks.
  - `coverImageUrl: string`

    URL of the video cover image or thumbnail.
  - `isAd: boolean`

    `true` if it is an ad.
  - `length: integer`

    Video length in seconds.
  - `likes: integer`

    Number of likes.
  - `comments: integer`

    Number of comments.
  - `views: integer`

    Number of views.
  - `shares: integer`

    Number of shares.
  - `engagementRate: number`

    Engagement rate of the video, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments + Shares)/ Followers*
  - `hashtags: array<string>`

    Keywords used in the video caption or description.
  - `audioId: string`

    Unique identifier of the audio track in the content.
  - `audioTitle: string`

    Title of the audio track.
  - `audioAuthor: string`

    Artist of the audio track.
  - `audioAlbum: string`

    Album name of the audio track.
  - `isDuetEnabled: boolean`

    `true` if duet is enabled.

**Example response**

```json
{
  "data": {
    "recentVideos": [
      {
        "publishTime": 1767651698000,
        "contentId": "7592006153727380766",
        "description": "What I Imagine pt. 🍟👚",
        "coverImageUrl": "https://p16-pu-sign-useast8.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o4nOXHCqlhQOW48cFeLIAkGfRcAGC3fQQHe5UN~tplv-tiktokx-origin.image?dr=14575&x-expires=1768014000&x-signature=HJyXLY1LcfVh0yjzkxdO1%2FnzN7A%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2",
        "isAd": false,
        "length": 74,
        "likes": 111100,
        "comments": 777,
        "views": 594300,
        "shares": 1607,
        "engagementRate": 0.191,
        "hashtags": []
      },
      {
        "publishTime": 1767646234000,
        "contentId": "7591982673988439327",
        "description": "That went by QUICK🥲",
        "coverImageUrl": "https://p16-pu-sign-useast8.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o0cXAuGDvIS1LJxRCqeCjsRyBgfsJEIfAIITyI~tplv-tiktokx-origin.image?dr=14575&x-expires=1768014000&x-signature=A7o%2FcOJ6GEcUs0F04sV9mPpzHFo%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=my2",
        "isAd": false,
        "length": 10,
        "likes": 570600,
        "comments": 7984,
        "views": 5800000,
        "shares": 35600,
        "engagementRate": 0.1059,
        "hashtags": []
      },
      "… 33 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "6b3d3226368e03a0f213f5697bf7312a",
  "timestamp": 1767939569931,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /tiktok/performance-history — Get Performance History

Source: https://docs.creatordb.app/api-reference/tiktok/get-performance-history.md
Credits: 3

Retrieve daily performance snapshots for a specified TikTok creator within a specific period, including upload activity, follower growth, engagement metrics, and video performance. Dates are returned as Unix timestamps in milliseconds.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uniqueId` | query | string | yes | TikTok account ID. Accepts `tiktok` or `@tiktok` (@ is stripped automatically). |
| `pastDayRange` | query | string | yes | Returns one data point per day over the requested range. For example, `30` returns the past 30 days of daily snapshots. Valid range: `1`-`365`. |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/tiktok/performance-history?uniqueId=charlidamelio&pastDayRange=30" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Response — `data` payload**

- `histories: array<object { timestamp, totalFollowers, totalFollowing, … 2 more }>`

  Historical performance snapshots, each containing metrics, and a corresponding Unix timestamp in milliseconds.

  - `timestamp: integer`

    The performance snapshot date, represented as a Unix timestamp in milliseconds.
  - `totalFollowers: integer`

    Total number of followers.
  - `totalFollowing: integer`

    Total number of accounts followed.
  - `totalContents: integer`

    Total number of videos.
  - `videosPerformanceRecent: object { likes, comments, views, … 2 more }`

    Performance metrics of the most recent TikTok videos.

    - `likes: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of likes.
      - `avg: integer`

        Average likes per video, rounded to an integer.
      - `median: integer`

        Median number of likes.
      - `min: integer`

        Minimum number of likes.
      - `max: integer`

        Maximum number of likes.
    - `comments: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of comments.
      - `avg: integer`

        Average comments per video, rounded to an integer.
      - `median: integer`

        Median number of comments.
      - `min: integer`

        Minimum number of comments.
      - `max: integer`

        Maximum number of comments.
    - `views: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of views.
      - `avg: integer`

        Average views per video, rounded to an integer.
      - `median: integer`

        Median number of views.
      - `min: integer`

        Minimum number of views.
      - `max: integer`

        Maximum number of views.
    - `shares: object { all, avg, median, … 2 more }`

      - `all: integer`

        Total number of shares.
      - `avg: integer`

        Average shares per video, rounded to an integer.
      - `median: integer`

        Median number of shares.
      - `min: integer`

        Minimum number of shares.
      - `max: integer`

        Maximum number of shares.
    - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

      Engagement performance metrics including rates, per-follower statistics, and consistency analysis.

      - `avgEngagementRate: number`

        Average engagement rate per video, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments + Shares)/ Followers*
      - `likesPerFollower: number`

        Average likes per follower, rounded to 4th decimal place.
      - `commentsPerFollower: number`

        Average comments per follower, rounded to 4th decimal place.
      - `viewsPerFollower: number`

        Average views per follower, rounded to 4th decimal place.
      - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

        Consistency of engagement performance.

        - … (depth limit)

**Example response**

```json
{
  "data": {
    "histories": [
      {
        "timestamp": 1767852641724,
        "totalFollowers": 155900000,
        "totalFollowing": 1289,
        "totalContents": 2893,
        "videosPerformanceRecent": {
          "likes": {
            "all": 11215700,
            "avg": 560785,
            "median": 226700,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 49820,
            "avg": 2491,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 202000000,
            "avg": 10100000,
            "median": 7750000,
            "min": 5000000,
            "max": 27800000
          },
          "shares": {
            "all": 121440,
            "avg": 6072,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "engagement": {
            "avgEngagementRate": 0.0442,
            "likesPerFollower": 0.0036,
            "commentsPerFollower": 0,
            "viewsPerFollower": 0.0648,
            "engagementConsistency": {
              "cv": 0.7354,
              "medianVsMean": 0.748,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      {
        "timestamp": 1767766241724,
        "totalFollowers": 156000000,
        "totalFollowing": 1287,
        "totalContents": 2892,
        "videosPerformanceRecent": {
          "likes": {
            "all": 11204200,
            "avg": 560210,
            "median": 226500,
            "min": 0,
            "max": 0
          },
          "comments": {
            "all": 49660,
            "avg": 2483,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "views": {
            "all": 201200000,
            "avg": 10060000,
            "median": 7650000,
            "min": 5000000,
            "max": 27700000
          },
          "shares": {
            "all": 121260,
            "avg": 6063,
            "median": 0,
            "min": 0,
            "max": 0
          },
          "engagement": {
            "avgEngagementRate": 0.0442,
            "likesPerFollower": 0.0036,
            "commentsPerFollower": 0,
            "viewsPerFollower": 0.0645,
            "engagementConsistency": {
              "cv": 0.7352,
              "medianVsMean": 0.7495,
              "topBottomRatio": 0,
              "consistencyScore": null,
              "consistencyLevel": null
            }
          }
        }
      },
      "… 9 more items"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "20fb4d4399fcf96d227bd016d6171858",
  "timestamp": 1767939041800,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/performance — Get Performance Information

Source: https://docs.creatordb.app/api-reference/tiktok/get-performance-information.md
Credits: —

Retrieve advanced performance information of a specified TikTok creator, including post activity, follower growth, engagement metrics, and content performance.<br /><br />Optionally pass `fields` in the request body to return only a subset of performance blocks. Requesting a subset bills fractionally, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, a request that includes `fields` returns a `400` error (`FractionalCallsNotEnabled`). For per-field costs, see [Field and Item Costs](/api-v3/field-and-item-costs#tiktok/performance). For how fractional costs work, see [Fractional Costs](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "tiktok"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/performance" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "kallmekris" }'
```

**Response — `data` payload**

- `contentCountByDays: object { 7d, 30d, 90d }`

  Published TikTok content over different time intervals.

  - `7d: integer`

    Number of contents published in the past 7 days.
  - `30d: integer`

    Number of contents published in the past 30 days.
  - `90d: integer`

    Number of contents published in the past 90 days.
- `ranking: object { totalFollowers, avgViews, avgEngagementRate }`

  Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.

  - `totalFollowers: object { global, country, language }`

    Percentile rank of the total follower count.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
  - `avgViews: object { global, country, language }`

    Percentile rank of the average views per video.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
  - `avgEngagementRate: object { global, country, language }`

    Percentile rank of the average engagement rate.

    - `global: number`

      Percentile rank compared to all creators in CreatorDB's database.
    - `country: number`

      Percentile rank among creators from the same country.
    - `language: number`

      Percentile rank among creators using the same primary language.
- `videosPerformanceRecent: object { likes, comments, views, … 2 more }`

  Performance metrics of the creator's recent TikTok videos.

  - `likes: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of likes.
    - `avg: integer`

      Average likes per video, rounded to an integer.
    - `median: integer`

      Median number of likes.
    - `min: integer`

      Minimum number of likes.
    - `max: integer`

      Maximum number of likes.
  - `comments: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of comments.
    - `avg: integer`

      Average comments per video, rounded to an integer.
    - `median: integer`

      Median number of comments.
    - `min: integer`

      Minimum number of comments.
    - `max: integer`

      Maximum number of comments.
  - `views: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of views.
    - `avg: integer`

      Average views per video, rounded to an integer.
    - `median: integer`

      Median number of views.
    - `min: integer`

      Minimum number of views.
    - `max: integer`

      Maximum number of views.
  - `shares: object { all, avg, median, … 2 more }`

    - `all: integer`

      Total number of shares.
    - `avg: integer`

      Average shares per video, rounded to an integer.
    - `median: integer`

      Median number of shares.
    - `min: integer`

      Minimum number of shares.
    - `max: integer`

      Maximum number of shares.
  - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

    Engagement performance metrics including rates, per-follower statistics and consistency analysis.

    - `avgEngagementRate: number`

      Average engagement rate per video, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments + Shares)/ Followers*
    - `likesPerFollower: number`

      Average likes per follower, rounded to 4th decimal place.
    - `commentsPerFollower: number`

      Average comments per follower, rounded to 4th decimal place.
    - `viewsPerFollower: number`

      Average views per follower, rounded to 4th decimal place.
    - `engagementConsistency: object { cv, medianVsMean, topBottomRatio, … 2 more }`

      Consistency of engagement performance.

      - `cv: number`

        *cv &#61; Standard Deviation of Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place. <br /> - Lower values indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `medianVsMean: number`

        *medianVsMean &#61; Median Engagement Rate/ Mean Engagement Rate* <br /> - The value is rounded to 4th decimal place <br /> - Values closer to `1` indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `topBottomRatio: number`

        *topBottomRatio &#61; avg(Top 3 Engagement)/avg(Bottom 3 Engagement)* <br /> - The value is rounded to 4th decimal place. <br /> - Lower ratios indicate more consistent performance. <br /> - *A value of `0` indicates insufficient data.*
      - `consistencyScore: integer,null`

        *consistencyScore &#61; 100 - [(cvScore\*weight_cv) + (topBottomScore\*weight_topBottom) + (medianVsMeanScore\*weight_medianVsMean)]* <br /> - The score is rounded to an integer. <br /> - A higher score indicates more stable and consistent performance. <br /> - If any of the three indicators is `0`, the `consistencyScore` will be `null`.
      - `consistencyLevel: "high" | "moderate" | "low" | null`

        A qualitative label based on the `consistencyScore`: <br /> - high: 81 - 100 <br /> - moderate: 51 - 80 <br /> - low: 0 - 50 <br /> - Returns `null` when the `consistencyScore` is `null`.
- `recentVideosGrowth: object { g7, g30, g90 }`

  Growth metrics for recent videos across 7, 30, and 90-day periods.

  - `g7: object { engagementRate }`

    Growth metrics over 7 days.

    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g30: object { engagementRate }`

    Growth metrics over 30 days.

    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.
  - `g90: object { engagementRate }`

    Growth metrics over 90 days.

    - `engagementRate: number`

      Growth rate of engagement rate, rounded to 4th decimal place.

**Example response**

```json
{
  "data": {
    "contentCountByDays": {
      "7d": 2,
      "30d": 12,
      "90d": 38
    },
    "followerGrowthIn30d": 0,
    "ranking": {
      "totalFollowers": {
        "global": 0.0459,
        "country": 0.0395,
        "language": 0.0375
      },
      "avgViews": {
        "global": 0.9183,
        "country": 0.9175,
        "language": 0.9128
      },
      "avgEngagementRate": {
        "global": 0.219,
        "country": 0.2332,
        "language": 0.2263
      }
    },
    "videosPerformanceRecent": {
      "likes": {
        "all": 3253500,
        "avg": 162675,
        "median": 139950,
        "min": 0,
        "max": 0
      },
      "comments": {
        "all": 16780,
        "avg": 839,
        "median": 0,
        "min": 0,
        "max": 0
      },
      "views": {
        "all": 19514700,
        "avg": 975735,
        "median": 795300,
        "min": 219000,
        "max": 2700000
      },
      "shares": {
        "all": 150040,
        "avg": 7502,
        "median": 0,
        "min": 0,
        "max": 0
      },
      "engagement": {
        "avgEngagementRate": 0.1638,
        "likesPerFollower": 0.0032,
        "commentsPerFollower": 0,
        "viewsPerFollower": 0.0193,
        "engagementConsistency": {
          "cv": 0.183,
          "medianVsMean": 0.973,
          "topBottomRatio": 0,
          "consistencyScore": null,
          "consistencyLevel": null
        }
      }
    }
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "497b42dc5ed0208ddc6ab552053e90ec",
  "timestamp": 1767938201026,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/profile — Get Profile Information

Source: https://docs.creatordb.app/api-reference/tiktok/get-profile-information.md
Credits: —

Retrieve profile information of a specified TikTok creator, including metadata, statistics, hashtags, and content analysis.<br /><br />Optionally pass `fields` in the request body to return only a subset of profile fields. You are billed the sum of the requested fields' costs, capped at the full-bundle price. Fractional calls must be enabled on your API key. Otherwise, requests that include a fields parameter return a `400` error (`FractionalCallsNotEnabled`). For per-field pricing, see [Field and Item Costs](/api-v3/field-and-item-costs#tiktok/profile). For how fractional calls work, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "uniqueId": "tiktok",
  "fields": [
    "displayName",
    "country",
    "totalFollowers"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/profile" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueId": "charlidamelio", "fields": ["displayName", "country"] }'
```

**Response — `data` payload**

- `uniqueId: string`

  Account handle.
- `displayName: string`

  Account name.
- `category: string`

  Professional account category.
- `avatarUrl: string`

  Account profile picture URL.
- `bio: string`

  The profile biography.
- `isBusinessAccount: boolean`

  `true` if it is a business account.
- `isPrivateAccount: boolean`

  `true` if it is a private account.
- `isVerified: boolean`

  `true` if the account is verified.
- `hasSponsors: boolean`

  `true` if there is sponsored content.
- `country: string`

  The country in **ISO 3166-1 alpha-3** format. For the country code list, see [here](https://docs.creatordb.app/api-v2/country-code).
- `mainLanguage: string`

  The primary language used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `languages: array<string>`

  All languages used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `secondLanguage: string`

  The secondary language used in posts, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
- `totalContents: integer`

  Total number of videos.
- `totalFollowing: integer`

  Total number of accounts followed.
- `totalFollowers: integer`

  Total number of followers.
- `subscriberGrowth: object { g7, g30, g90 }`

  Follower growth metrics over 7, 30, and 90-day periods.

  - `g7: number`

    Follower growth over 7 days, rounded to 4th decimal place.
  - `g30: number`

    Follower growth over 30 days, rounded to 4th decimal place.
  - `g90: number`

    Follower growth over 90 days, rounded to 4th decimal place.
- `hashtags: array<object { name, contentCount }>`

  Hashtags used in TikTok posts and usage statistics.

  - `name: string`

    Hashtags used in post captions or descriptions.
  - `contentCount: integer`

    Number of contents using the hashtag.
- `niches: array<string>`

  Granular subcategories of content topics identified by CreatorDB's AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
- `otherLinks: array<object { title, url }>`

  Linked websites.

  - `title: string`

    The link name.
  - `url: string`

    The profile or website URL.
- `lastPublishTime: integer`

  Time the last content was uploaded, represented as a Unix timestamp in milliseconds.
- `lastDbUpdateTime: integer`

  Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.

**Example response**

```json
{
  "data": {
    "uniqueId": "charlidamelio",
    "displayName": "charli d’amelio",
    "category": "",
    "avatarUrl": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310052907548688430~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=d917d4bb&x-expires=1768021200&x-signature=YzmaK9NcAS6NfN%2BNcV1LLX3jJec%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=f20df69d&idc=maliva",
    "bio": ":)",
    "isBusinessAccount": false,
    "isPrivateAccount": false,
    "isVerified": true,
    "hasSponsors": false,
    "country": "USA",
    "mainLanguage": "eng",
    "languages": [
      "eng"
    ],
    "secondLanguage": null,
    "totalContents": 25,
    "totalFollowers": 155900000,
    "totalFollowing": 1289,
    "subscriberGrowth": {
      "g7": 0.0012,
      "g30": 0.0045,
      "g90": 0.0123
    },
    "hashtags": [
      {
        "name": "#pradamode",
        "contentCount": 2
      },
      {
        "name": "#redbulldanceyourstyle",
        "contentCount": 2
      },
      "… 7 more items"
    ],
    "niches": [
      "dance_All",
      "entertainment_All",
      "… 1 more items"
    ],
    "otherLinks": [
      {
        "title": "",
        "url": "https://www.tiktok.com/link/v2?aid=1988&lang=en&scene=bio_url&target=win.gs/DanceYourStyleLA"
      }
    ],
    "lastPublishTime": 1763599023000,
    "lastDbUpdateTime": 1767830400000
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "e2817236a4f325570bfe6ee5fae33f23",
  "timestamp": 1767936363120,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /tiktok/niches — List Niches

Source: https://docs.creatordb.app/api-reference/tiktok/list-niches.md
Credits: 1

Retrieve all available TikTok niche categories and their creator counts. Niches categorize creators by content themes.

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/tiktok/niches" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>"
```

**Example response**

```json
{
  "data": [
    {
      "id": "id_capcut_All",
      "name": "Capcut",
      "category": "All",
      "channelCount": 252193
    },
    {
      "id": "id_palagi_All",
      "name": "Palagi",
      "category": "All",
      "channelCount": 78266
    },
    "… 8 more items"
  ],
  "traceId": "13b6aee50b7a305432c39a7baf7fe7a2",
  "timestamp": 1772096850140,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "creditsUsed": 1,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/content-search — Search Content

Source: https://docs.creatordb.app/api-reference/tiktok/search-content.md
Credits: —

Search for TikTok content (videos) across all creators in the CreatorDB database using content-level and creator-level filters. Enables discovery of specific content by performance metrics, hashtags, audio, and more. By default, the `contentList` is sorted by `publishTime` descending (newest first). Custom sorting can be applied using the `sortBy` parameter.

**Request body**

```json
{
  "filters": [
    {
      "filterName": "plays",
      "op": ">",
      "value": 5000000
    },
    {
      "filterName": "publishTime",
      "op": "<",
      "value": 7
    },
    {
      "filterName": "engagement",
      "op": ">",
      "value": 0.05
    }
  ],
  "sortBy": "plays",
  "desc": true,
  "pageSize": 20,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/content-search" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `contentList: array<object { contentId, description, thumbnail, … 12 more }>`

  Content items matching the search filters.

  - `contentId: string`

    The unique video ID. URL: `https://www.tiktok.com/@{uniqueId}/video/{contentId}`
  - `description: string`

    The video caption.
  - `thumbnail: string`

    The Thumbnail or cover image URL.
  - `url: string`

    Direct URL of the content.
  - `publishTime: integer`

    Publish time, represented as a Unix timestamp in milliseconds.
  - `lengthSec: integer`

    Duration of the video in seconds.
  - `plays: integer`

    Number of plays.
  - `likes: integer`

    Number of likes.
  - `comments: integer`

    Number of comments.
  - `shares: integer`

    Number of shares.
  - `engagementRate: number`

    Engagement rate, rounded to 4th decimal place. <br /> *Engagement Rate &#61;(Likes + Comments + Shares) / Followers.
  - `hashtags: array<string>`

    Keywords in the video description.
  - `audioTitle: string`

    Title of the audio in the content.
  - `audioAuthor: string`

    Artist of the audio track.
  - `creator: object { uniqueId, displayName, avatarUrl, … 1 more }`

    Creator information for the content.

    - `uniqueId: string`

      Account handle.
    - `displayName: string`

      Account display name.
    - `avatarUrl: string`

      Account profile picture URL.
    - `totalFollowers: integer`

      Total number of followers.
- `totalResults: integer`

  Total number of content items matching the search filters.
- `hasNextPage: boolean`

  `true` if there is a next page of results.
- `nextOffset: integer`

  The offset value for retrieving the next page of results.

**Example response**

```json
{
  "data": {
    "contentList": [
      {
        "contentId": "7318379374288424225",
        "description": "hope everyone is having a nice day! ✨🤍 #xmas #christmas #xmas2023 #tryon #foryoupage #fyp #foryou",
        "thumbnail": "https://p19-common-sign-useastred.tiktokcdn-eu.com/...",
        "url": "https://www.tiktok.com/@.....aaaaesthetic/video/7318379374288424225",
        "publishTime": 1703942994000,
        "lengthSec": 11,
        "plays": 1947,
        "likes": 239,
        "comments": 7,
        "shares": 1,
        "engagementRate": 0.1269,
        "hashtags": [
          "#xmas",
          "#foryoupage"
        ],
        "audioTitle": "original sound - User",
        "audioAuthor": "User",
        "creator": {
          "uniqueId": ".....aaaaesthetic",
          "displayName": ".....aaesthetic",
          "avatarUrl": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/...",
          "totalFollowers": 38100
        }
      }
    ],
    "totalResults": 3200,
    "nextOffset": 20
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/search — Search Creators

Source: https://docs.creatordb.app/api-reference/tiktok/search-creators.md
Credits: 1 per 10 filters

Search for TikTok creators using advanced filters such as `displayName`, follower count, content performance, and more. Supports fuzzy search, pagination, and multiple filter combinations. At least one filter is required. The `creatorList` is, by default, sorted by `displayName`. Custom sorting can be applied using the `sortBy` parameter. <br /><br />Optionally pass `fields` to enrich each search result with data from other endpoints. Enrichment is billed per result returned, using each endpoint's own pricing rules. Fractional calls must be enabled on your API key. For details, see [Fractional Calls](/api-v3/fractional-calls).

**Request body**

```json
{
  "filters": [
    {
      "filterName": "displayName",
      "op": "=",
      "value": "beast",
      "isFuzzySearch": true
    }
  ],
  "desc": true,
  "sortBy": "displayName",
  "pageSize": 10,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/search" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{
    "filters": [
      {"filterName": "avgVideosEngagementRate", "op": ">", "value": 0.03},
      {"filterName": "totalContents", "op": ">", "value": 20},
      {"filterName": "followerGrowthIn30d", "op": ">", "value": 1000},
      {"filterName": "avgVideosLikes", "op": ">", "value": 500}
    ],
    "sortBy": "avgVideosEngagementRate",
    "desc": true,
    "pageSize": 50,
    "offset": 0
  }'
```

**Response — `data` payload**

- `creatorList: array<object { displayName, uniqueId, avatarUrl, … 7 more }>`

  Creator objects matching the search query.

  - `displayName: string`

    The TikTok account name.
  - `uniqueId: string`

    The TikTok handle.
  - `avatarUrl: string`

    The profile picture URL.
  - `totalFollowers: integer`

    Total number of followers.
  - `profile?: object { uniqueId, displayName, category, … 19 more }`

    Profile data for this creator. Present only when requested via `fields.profile`.

    - `uniqueId?: string`

      Account handle.
    - `displayName?: string`

      Account name.
    - `category?: string`

      Professional account category.
    - `avatarUrl?: string`

      Account profile picture URL.
    - `bio?: string`

      The profile biography.
    - `isBusinessAccount?: boolean`

      `true` if it is a business account.
    - `isPrivateAccount?: boolean`

      `true` if it is a private account.
    - `isVerified?: boolean`

      `true` if the account is verified.
    - `hasSponsors?: boolean`

      `true` if there is sponsored content.
    - `country?: string`

      The country in **ISO 3166-1 alpha-3** format. For the country code list, see [here](https://docs.creatordb.app/api-v2/country-code).
    - `mainLanguage?: string`

      The primary language used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `languages?: array<string>`

      All languages used in posts, represented in **ISO 639-3** format. For the language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `secondLanguage?: string`

      The secondary language used in posts, represented in **ISO 639-3** format. For language code list, see [here](https://docs.creatordb.app/api-v3/language-code).
    - `totalContents?: integer`

      Total number of videos.
    - `totalFollowing?: integer`

      Total number of accounts followed.
    - `totalFollowers?: integer`

      Total number of followers.
    - `subscriberGrowth?: object { g7, g30, g90 }`

      Follower growth metrics over 7, 30, and 90-day periods.

      - `g7: number`

        Follower growth over 7 days, rounded to 4th decimal place.
      - `g30: number`

        Follower growth over 30 days, rounded to 4th decimal place.
      - `g90: number`

        Follower growth over 90 days, rounded to 4th decimal place.
    - `hashtags?: array<object { name, contentCount }>`

      Hashtags used in TikTok posts and usage statistics.

      - `name: string`

        Hashtags used in post captions or descriptions.
      - `contentCount: integer`

        Number of contents using the hashtag.
    - `niches?: array<string>`

      Granular subcategories of content topics identified by CreatorDB's AI model, which analyzes and groups keywords, hashtags, and tags used by creators.
    - `otherLinks?: array<object { title, url }>`

      Linked websites.

      - `title: string`

        The link name.
      - `url: string`

        The profile or website URL.
    - `lastPublishTime?: integer`

      Time the last content was uploaded, represented as a Unix timestamp in milliseconds.
    - `lastDbUpdateTime?: integer`

      Last update time of the creator profile and statistics in the CreatorDB database, represented as a Unix timestamp in milliseconds.
  - `performance?: object { contentCountByDays, ranking, videosPerformanceRecent, … 1 more }`

    Performance data for this creator. Present only when requested via `fields.performance`.

    - `contentCountByDays?: object { 7d, 30d, 90d }`

      Published TikTok content over different time intervals.

      - `7d: integer`

        Number of contents published in the past 7 days.
      - `30d: integer`

        Number of contents published in the past 30 days.
      - `90d: integer`

        Number of contents published in the past 90 days.
    - `ranking?: object { totalFollowers, avgViews, avgEngagementRate }`

      Percentile rankings for various performance metrics, benchmarked at the global, country, or language level. A value of `1.0` indicates top 1%, while `0.5` represents the median.

      - `totalFollowers: object { global, country, language }`

        Percentile rank of the total follower count.

        - … (depth limit)
      - `avgViews: object { global, country, language }`

        Percentile rank of the average views per video.

        - … (depth limit)
      - `avgEngagementRate: object { global, country, language }`

        Percentile rank of the average engagement rate.

        - … (depth limit)
    - `videosPerformanceRecent?: object { likes, comments, views, … 2 more }`

      Performance metrics of the creator's recent TikTok videos.

      - `likes: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `comments: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `views: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `shares: object { all, avg, median, … 2 more }`

        - … (depth limit)
      - `engagement: object { avgEngagementRate, likesPerFollower, commentsPerFollower, … 2 more }`

        Engagement performance metrics including rates, per-follower statistics and consistency analysis.

        - … (depth limit)
    - `recentVideosGrowth?: object { g7, g30, g90 }`

      Growth metrics for recent videos across 7, 30, and 90-day periods.

      - `g7: object { engagementRate }`

        Growth metrics over 7 days.

        - … (depth limit)
      - `g30: object { engagementRate }`

        Growth metrics over 30 days.

        - … (depth limit)
      - `g90: object { engagementRate }`

        Growth metrics over 90 days.

        - … (depth limit)
  - `audience?: object { audienceLocations, audienceGender, audienceAvgAge, … 1 more }`

    Audience demographics for this creator. Present only when requested via `fields.audience`.

    - `audienceLocations?: array,null`

      Country location of the audience, sorted by descending share.
    - `audienceGender?: object,null`

      Gender distribution of the audience.
    - `audienceAvgAge?: integer,null`

      Average age of the audience, rounded to an integer.
    - `audienceAgeBreakdown?: array,null`

      Distribution of the audience by age range.
  - `contact?: object { emails }`

    Contact information for this creator. Present only when requested via `fields.contact`.

    - `emails?: array<string>`

      Associated email addresses. Empty if unavailable.
  - `content-detail?: object { recentVideos }`

    Recent content published by this creator. Present only when requested via `fields.content-detail`.

    - `recentVideos?: array<object { publishTime, contentId, description, … 14 more }>`

      Data of recent TikTok videos.

      - `publishTime: integer`

        Publish time, represented as a Unix timestamp in milliseconds.
      - `contentId: string`

        The unique identifier. Represented as follows: `https://www.tiktok.com/@{uniqueId}/video/{contentId}`
      - `description: string`

        The video caption, including emojis, hashtags, and line breaks.
      - `coverImageUrl: string`

        URL of the video cover image or thumbnail.
      - `isAd: boolean`

        `true` if it is an ad.
      - `length: integer`

        Video length in seconds.
      - `likes: integer`

        Number of likes.
      - `comments: integer`

        Number of comments.
      - `views: integer`

        Number of views.
      - `shares: integer`

        Number of shares.
      - `engagementRate: number`

        Engagement rate of the video, rounded to 4th decimal place. <br /> - *Engagement Rate &#61; (Likes + Comments + Shares)/ Followers*
      - `hashtags: array<string>`

        Keywords used in the video caption or description.
      - `audioId: string`

        Unique identifier of the audio track in the content.
      - `audioTitle: string`

        Title of the audio track.
      - `audioAuthor: string`

        Artist of the audio track.
      - `audioAlbum: string`

        Album name of the audio track.
      - `isDuetEnabled: boolean`

        `true` if duet is enabled.
  - `performance-history?: object { histories }`

    Daily performance snapshots for this creator. Present only when requested via `fields.performance-history`.

    - `histories: array<object { timestamp, totalFollowers, totalFollowing, … 2 more }>`

      Historical performance snapshots, each containing metrics, and a corresponding Unix timestamp in milliseconds.

      - `timestamp: integer`

        The performance snapshot date, represented as a Unix timestamp in milliseconds.
      - `totalFollowers: integer`

        Total number of followers.
      - `totalFollowing: integer`

        Total number of accounts followed.
      - `totalContents: integer`

        Total number of videos.
      - `videosPerformanceRecent: object { likes, comments, views, … 2 more }`

        Performance metrics of the most recent TikTok videos.

        - … (depth limit)
- `totalResults: integer`

  Number of results for this search query.
- `hasNextPage: boolean`

  `true` if there is a next page of results.
- `nextOffset: integer`

  The offset value to use for retrieving results on the next page.

**Example response**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "Ty Myers",
        "uniqueId": "tymyers",
        "avatarUrl": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/95a314aa4befbecaa494aab7e5f6d0cb~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=e4f46e62&x-expires=1768428000&x-signature=Ms7U88fImoMAYs24EQrMEFjXFeY%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=sg1",
        "totalFollowers": 779800
      },
      {
        "displayName": "barbie",
        "uniqueId": "barbiechicc",
        "avatarUrl": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/30332117a44f5d110f8275983e3fb0fc~tplv-tiktokx-cropcenter:720:720.jpeg?dr=14579&refresh_token=bb9952be&x-expires=1753714800&x-signature=zotHqzcGBpvhUi4mN1shxuXzMMU%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=my2",
        "totalFollowers": 235500
      },
      "… 6 more items"
    ],
    "hasNextPage": false,
    "nextOffset": 0
  },
  "creditsUsed": 1,
  "creditsAvailable": 975,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "traceId": "f790925aeaa82fa64b24c1400cbf5e3e",
  "timestamp": 1768326490384,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### POST /tiktok/submitCreators — Submit Creators

Source: https://docs.creatordb.app/api-reference/tiktok/submit-creators.md
Credits: —

Submit new TikTok creators to the CreatorDB database for indexing. Accepted creators enter a processing queue and become available via the other TikTok endpoints once first scraped. You are billed per newly accepted creator. Creators already indexed (`done`) or rejected (`rejected`) are not charged. For the current per-creator cost, see [API Credit Usage](/api-v3/api-credit-usage).

**Request body**

```json
{
  "uniqueIds": [
    "charlidamelio",
    "khaby.lame"
  ]
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/tiktok/submitCreators" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{ "uniqueIds": ["charlidamelio", "khaby.lame"] }'
```

**Response — `data` payload**

- `results: array<object { uniqueId, status, existingUniqueId }>`

  Per-creator results, one entry per submitted TikTok handle, in the same submission order.

  - `uniqueId: string`

    The submitted TikTok handle.
  - `status: "accepted" | "done" | "rejected"`

    The creator's indexing status. - `accepted`: entered the processing queue (billable).<br/> - `done`: already indexed in the database (not charged). <br/> - `rejected`: invalid or blacklisted (not charged). <br/> For the current per-creator cost, see [API Credit Usage](/api-v3/api-credit-usage).
  - `existingUniqueId: string,null`

    Returns the existing CreatorDB identifier when the indexing status is `done`. Otherwise, `null`.

**Example response**

```json
{
  "creditsUsed": 1,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

## Sponsor / Brand

### GET /sponsor/information — Get Brand Information

Source: https://docs.creatordb.app/api-reference/sponsor/get-brand-information.md
Credits: 2

Returns identity and metadata for a specific brand — including company details, industries, key people, social links, competitors, and basic activity indicators. Does not include sponsor performance data or sponsored creator lists.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `brandId` | query | string | yes |  |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/sponsor/information" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `brandId: string`

  Unique brand identifier, typically the brand's primary domain.
- `name: string`

  Brand's display name.
- `alias: array<string>`

  Alternative domains and names for this brand.
- `logo: string`

  URL of the brand's logo.
- `description: string`

  Short description of the brand.
- `companySize: string`

  Estimated company size by employee count, as a range (e.g., `501-1,000`).
- `keyPeople: array<string>`

  Notable people associated with the brand.
- `industries: array<string>`

  Industries the brand operates in. See [Industry List](https://docs.creatordb.app/api-v2/industry-list) for all possible values.
- `country: string`

  Headquarters country in ISO 3166-1 alpha-3 format.
- `location: string`

  City-level headquarters location.
- `website: string`

  Brand's official website URL.
- `socialMedia: array<object { platform, url }>`

  Brand's social media presence.

  - `platform: string`

    Social media platform name. Canonical values: see PRD Reference: socialMedia standardized platforms.
  - `url: string`

    URL to the brand's social media profile
- `competitors: array<string>`

  Known competitor brands.
- `totalSponsoredContent: integer`

  Total count of sponsored content pieces detected across the platforms in `activePlatforms`.
- `activePlatforms: array<string>`

  Social media platforms where this brand's sponsored content has been detected.

**Example response**

```json
{
  "data": {
    "brandId": "acer.com",
    "name": "Acer",
    "alias": [
      "acer.co",
      "store.acer.com",
      "… 1 more items"
    ],
    "logo": "https://i.imgur.com/bazrFjP.png",
    "description": "Acer is a Taiwanese multinational hardware and electronics corporation.",
    "companySize": "501-1,000",
    "keyPeople": [
      "Carolyn Yeh",
      "George Huang",
      "… 1 more items"
    ],
    "industries": [
      "Computer",
      "ConsumerElectronics",
      "… 1 more items"
    ],
    "country": "TWN",
    "location": "Taipei, Taiwan",
    "website": "http://www.acer.com",
    "socialMedia": [
      {
        "platform": "facebook",
        "url": "https://www.facebook.com/Acer"
      }
    ],
    "competitors": [
      "Apple",
      "HP",
      "… 1 more items"
    ],
    "totalSponsoredContent": 278,
    "activePlatforms": [
      "youtube",
      "instagram"
    ]
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /sponsor/summary — Get Brand Summary

Source: https://docs.creatordb.app/api-reference/sponsor/get-brand-summary.md
Credits: 25

Returns a non-paginated summary object for a brand, combining creator roster rollups and platform-level performance totals for both YouTube and Instagram. Includes YouTube-specific metrics: estimated brand spend, CPM, and CPE.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `brandId` | query | string | yes |  |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/sponsor/summary" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `summary: object { totalSponsoredCreators, totalSponsoredContent, youtube, … 1 more }`

  Summary of this brand's sponsored activity: cross-platform totals and per-platform breakdowns (YouTube, Instagram).

  - `totalSponsoredCreators: integer`

    Total number of creators this brand sponsors across YouTube and Instagram. Creators active on both platforms are counted twice.
  - `totalSponsoredContent: integer`

    Total number of sponsored content pieces this brand sponsors across YouTube and Instagram.
  - `youtube: object { creators, performance }`

    Creator roster and aggregate performance metrics for this brand's sponsored YouTube activity.

    - `creators: object { sponsoredCreators, sponsoredContent, sponsoredContent30d, … 2 more }`

      Summary of this brand's sponsored YouTube creators: total counts, recent sponsored content volume, and breakdowns by creator location and language.

      - `sponsoredCreators: integer`

        Total unique creators sponsored by this brand on YouTube.
      - `sponsoredContent: integer`

        Total number of sponsored content pieces from this brand on YouTube.
      - `sponsoredContent30d: integer`

        Sponsored content pieces from this brand published on YouTube in the last 30 days.
      - `creatorLocationBreakdown: array<object { key, count, share }>`

        Top 5 countries of this brand's sponsored YouTube creators, ranked by count. Shares across the top 5 may sum to less than 100%.

        - … (depth limit)
      - `creatorLanguageBreakdown: array<object { key, count, share }>`

        Top 5 languages of this brand's sponsored YouTube creators, ranked by count. Share across the top 5 may sum to less than 100%.

        - … (depth limit)
    - `performance: object { estimatedTotalSpend7d, estimatedTotalSpend30d, estimatedTotalSpend90d, … 7 more }`

      Aggregate metrics for this brand's sponsored YouTube activity, covering estimated spend, efficiency ratios (CPM, CPE), engagement totals, and rolling growth.

      - `estimatedTotalSpend7d: number,null`

        Estimated amount (USD) spent by this brand on sponsored YouTube creators over a rolling 7-day window. Returns null when no sponsored creator has a price estimate available.
      - `estimatedTotalSpend30d: number,null`

        Estimated amount (USD) spent by this brand on sponsored YouTube creators over a rolling 30-day window. Returns null when no sponsored creator has a price estimate available.
      - `estimatedTotalSpend90d: number,null`

        Estimated amount (USD) spent by this brand on sponsored YouTube creators over a rolling 90-day window. Returns null when no sponsored creator has a price estimate available.
      - `estimatedCPM30d: number,null`

        Cost per Mille (CPM, in USD) of the brand over a rolling 30-day window. < /br> CPM = `estimatedTotalSpend30d` /`views30d` x 1000 < /br> Returns `null` when the estimated total spend or the 30-day sponsored video views data is `null` or `0`. This is the brand's aggregate CPM across all sponsored content in the window. For per-video CPM, see the `sponsor/performance` endpoint.
      - `estimatedCPE30d: number,null`

        Cost per Engagement (CPE, in USD) for this brand over a rolling 30-day window. Engagement is defined as likes plus comments on sponsored content published in the window.< /b> CPE = `estimatedTotalSpend30d` / sum(`likes` + `comments`) < /br> Returns `null` when `estimatedTotalSpend30d` is `null` or the denominator is `0`.
      - `views: object { total, avg, median, … 3 more }`

        Summary statistics of views on this brand's sponsored YouTube content.

        - … (depth limit)
      - `likes: object { total, avg, median, … 2 more }`

        Summary statistics of likes on this brand's sponsored YouTube content.

        - … (depth limit)
      - `comments: object { total, avg, median, … 2 more }`

        Summary statistics of comments on this brand's sponsored YouTube content.

        - … (depth limit)
      - `engagement: object { avgEngagementRate }`

        Average engagement rate across this brand's sponsored YouTube content.

        - … (depth limit)
      - `growth30d: object { viewsGrowth, likesGrowth, commentsGrowth, … 1 more }`

        Rolling 30-day growth ratios for this brand's sponsored YouTube content, covering views, likes, comments, and engagement.

        - … (depth limit)
  - `instagram: object { creators, performance }`

    Creator roster and aggregate performance metrics for this brand's sponsored Instagram activity.

    - `creators: object { sponsoredCreators, sponsoredContent, sponsoredContent30d, … 2 more }`

      Summary of this brand's sponsored Instagram creators: total counts, recent sponsored content volume, and breakdowns by creator location and language.

      - `sponsoredCreators: integer`

        Total unique creators sponsored by this brand on Instagram.
      - `sponsoredContent: integer`

        Total number of sponsored content pieces from this brand on Instagram (all-time).
      - `sponsoredContent30d: integer`

        Sponsored content pieces from this brand published on Instagram in the last 30 days.
      - `creatorLocationBreakdown: array<object { key, count, share }>`

        Top 5 countries of this brand's sponsored Instagram creators, ranked by count. Shares across the top 5 may sum to less than 100%.

        - … (depth limit)
      - `creatorLanguageBreakdown: array<object { key, count, share }>`

        Top 5 languages of this brand's sponsored Instagram creators, ranked by count. Share across the top 5 may sum to less than 100%.

        - … (depth limit)
    - `performance: object { estimatedTotalSpend7d, estimatedTotalSpend30d, estimatedTotalSpend90d, … 7 more }`

      Aggregate metrics for this brand's sponsored Instagram activity, covering engagement totals, and rolling growth. Performance metrics for this brand's sponsored Instagram activity. Spend and efficiency fields are currently placeholders (always `null`) and will be populated when Instagram pricing data becomes available.

      - `estimatedTotalSpend7d: null`

        Not yet available for Instagram. Always returns `null`. See parent object description.
      - `estimatedTotalSpend30d: null`

        Not yet available for Instagram. Always returns `null`. See parent object description.
      - `estimatedTotalSpend90d: null`

        Not yet available for Instagram. Always returns `null`. See parent object description.
      - `estimatedCPM30d: null`

        Not yet available for Instagram. Always returns `null`. See parent object description.
      - `estimatedCPE30d: null`

        Not yet available for Instagram. Always returns `null`. See parent object description.
      - `views: object { total, avg, median, … 2 more }`

        Summary statistics of views on this brand's sponsored Instagram posts. Sum of views on this brand's sponsored Instagram posts over a rolling 30-day window is unavailable.

        - … (depth limit)
      - `likes: object { total, avg, median, … 2 more }`

        Summary statistics of likes on this brand's sponsored Instagram posts.

        - … (depth limit)
      - `comments: object { total, avg, median, … 2 more }`

        Summary statistics of comments on this brand's sponsored Instagram posts.

        - … (depth limit)
      - `engagement: object { avgEngagementRate }`

        Average engagement rate across this brand's sponsored Instagram posts.

        - … (depth limit)
      - `growth30d: object { viewsGrowth, likesGrowth, commentsGrowth, … 1 more }`

        Rolling 30-day growth ratios for this brand's sponsored Instagram content, covering views, likes, comments, and engagement.

        - … (depth limit)

**Example response**

```json
{
  "data": {
    "summary": {
      "totalSponsoredCreators": 49,
      "totalSponsoredContent": 278,
      "youtube": {
        "creators": {
          "sponsoredCreators": 34,
          "sponsoredContent": 156,
          "sponsoredContent30d": 35,
          "creatorLocationBreakdown": [
            {
              "count": 12,
              "share": 0.4
            }
          ],
          "creatorLanguageBreakdown": [
            {
              "key": "eng",
              "count": 12,
              "share": 0.4
            }
          ]
        },
        "performance": {
          "estimatedTotalSpend7d": 28000,
          "estimatedTotalSpend30d": 100000,
          "estimatedTotalSpend90d": 220000,
          "estimatedCPM30d": 8.51,
          "estimatedCPE30d": 0.31,
          "views": {
            "total": 452000000,
            "avg": 75374,
            "median": 62000,
            "min": 1200,
            "max": 890000,
            "views30d": 11758366
          },
          "likes": {
            "total": 452000000,
            "avg": 75374,
            "median": 62000,
            "min": 1200,
            "max": 890000
          },
          "comments": {
            "total": 452000000,
            "avg": 75374,
            "median": 62000,
            "min": 1200,
            "max": 890000
          },
          "engagement": {
            "avgEngagementRate": 0.0352
          },
          "growth30d": {
            "viewsGrowth": 0.3261,
            "likesGrowth": 0.2119,
            "commentsGrowth": 0.2976,
            "engagementGrowth": -0.0831
          }
        }
      },
      "instagram": {
        "creators": {
          "sponsoredCreators": 34,
          "sponsoredContent": 156,
          "sponsoredContent30d": 35,
          "creatorLocationBreakdown": [
            {
              "count": 12,
              "share": 0.4
            }
          ],
          "creatorLanguageBreakdown": [
            {
              "count": 12,
              "share": 0.4
            }
          ]
        },
        "performance": {
          "estimatedTotalSpend7d": null,
          "estimatedTotalSpend30d": null,
          "estimatedTotalSpend90d": null,
          "estimatedCPM30d": null,
          "estimatedCPE30d": null,
          "views": {
            "total": 452000000,
            "avg": 75374,
            "median": 62000,
            "min": 1200,
            "max": 890000
          },
          "likes": {
            "total": 452000000,
            "avg": 75374,
            "median": 62000,
            "min": 1200,
            "max": 890000
          },
          "comments": {
            "total": 452000000,
            "avg": 75374,
            "median": 62000,
            "min": 1200,
            "max": 890000
          },
          "growth30d": {
            "viewsGrowth": 0.3261,
            "likesGrowth": 0.2119,
            "commentsGrowth": 0.2976,
            "engagementGrowth": -0.0831
          }
        }
      }
    }
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /sponsor/audience — Get Sponsored Creator Demographics

Source: https://docs.creatordb.app/api-reference/sponsor/get-sponsored-creator-demographics.md
Credits: 25

Returns audience demographics for a brand's sponsored YouTube and Instagram creators when available. Using optional platform filters returns a single key.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `brandId` | query | string | yes |  |
| `platform` | query | string | no |  |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/sponsor/audience" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `youtube?: object,null`

  Audience data for this brand's YouTube sponsored creators. Returns `null` when the brand has no sponsored YouTube channels.
- `instagram?: object,null`

  Audience demographics keyed by platform. When the platform parameter filters the query, only the matching platform's key is returned. Keys for platforms without data are absent from the response.

**Example response**

```json
{
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /sponsor/performance — Get Sponsored Creator Performance

Source: https://docs.creatordb.app/api-reference/sponsor/get-sponsored-creator-performance.md
Credits: 25

Returns performance metrics for creators sponsored by a brand on YouTube or Instagram. For each creator, the response includes comparison stats (sponsored vs. overall performance), estimated cost and CPM (YouTube only), and performance details for their individual posts or videos.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `brandId` | query | string | yes |  |
| `platform` | query | string | yes |  |
| `pageSize` | query | string | no |  |
| `offset` | query | string | no |  |
| `sortBy` | query | string | no |  |
| `desc` | query | string | no |  |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/sponsor/performance" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `sponsoredCreators: array<object { creatorId, displayName, platform, … 6 more }>`

  - `creatorId: string`

    Platform-specific creator identifier (`channelId` for YouTube, `uniqueId` for Instagram).
  - `displayName: string`

    Creator's display name.
  - `platform: "youtube" | "instagram"`

    Platform for which this creator's sponsored content performance was queried. Matches the `platform` request parameter.
  - `creatorTotalStats: object { avgEngagementRate, avgViews, avgLikes, … 3 more }`

    This creator's overall performance stats across all tracked content (sponsored and non-sponsored). Use as a baseline to compare against `creatorAllSponsoredStats` and `creatorThisBrandSponsoredStats`.

    - `avgEngagementRate: number`

      Average engagement rate across all of this creator's tracked content (sponsored and non-sponsored). Expressed as a decimal (e.g., 0.0452 = 4.52%).
    - `avgViews: number,null`

      Average views per content piece across all of this creator's tracked content (sponsored and non-sponsored).
    - `avgLikes: number`

      Average likes per content piece across all of this creator's tracked content (sponsored and non-sponsored).
    - `avgComments: number`

      Average comments per content piece across all of this creator's tracked content (sponsored and non-sponsored).
    - `contentCount: integer`

      Number of tracked content pieces used to calculate the averages in this `creatorTotalStats` object.
    - `latestContentDate: integer`

      Unix timestamp (in milliseconds) of this creator's most recent content, across all content types (sponsored or non-sponsored).
  - `creatorAllSponsoredStats: object { avgEngagementRate, avgViews, avgLikes, … 3 more }`

    This creator's overall performance stats across all tracked content (sponsored and non-sponsored).

    - `avgEngagementRate: number`

      Average engagement rate across all of this creator's sponsored content (any brand). Expressed as a decimal (e.g., 0.0412 = 4.12%).
    - `avgViews: number,null`

      Average views per piece across all of this creator's sponsored content (any brand). May be null if view data is unavailable.
    - `avgLikes: number`

      Average likes per piece across all of this creator's sponsored content (any brand).
    - `avgComments: number`

      Average comments per piece across all of this creator's sponsored content (any brand).
    - `sponsoredCount: integer`

      Number of this creator's sponsored content pieces (any brand) used to calculate the averages in this creatorAllSponsoredStats object.
    - `latestSponsoredContentDate: integer`

      Unix timestamp (in milliseconds) of this creator's most recent sponsored content (any brand).
  - `creatorSpecificSponsoredStats: object { avgEngagementRate, avgViews, avgLikes, … 3 more }`

    This creator's performance stats across their sponsored content for the queried brand. Compare against `creatorTotalStats` (overall baseline) and `creatorAllSponsoredStats` (all-brand sponsored performance) to evaluate brand-specific performance.

    - `avgEngagementRate: number`

      Average engagement rate across this creator's sponsored content for the queried brand. Expressed as a decimal (e.g., 0.0379 = 3.79%).
    - `avgViews: number`

      Average views per piece across this creator's sponsored content for the queried brand.
    - `avgLikes: number`

      Average likes per piece across this creator's sponsored content for the queried brand.
    - `avgComments: number`

      Average comments per piece across this creator's sponsored content for the queried brand.
    - `sponsoredCount: integer`

      Number of this creator's sponsored content pieces for the queried brand used to calculate the averages in this `creatorSpecificSponsoredStats` object.
    - `latestSponsoredContentDate: integer`

      Unix timestamp (in milliseconds) of this creator's most recent sponsored content for the queried brand.
  - `estimatedCost: number,null`

    Sum of estimated prices (in USD) across this creator's sponsored videos for the queried brand. YouTube only — returns `null` for Instagram queries.
  - `estimatedCreatorCPM: number,null`

    Estimated cost per 1,000 views (in USD) for this creator's sponsored content for the queried brand. YouTube only. Calculated as 1000 × (`estimatedCost` ÷ `total views`), summed across this creator's sponsored videos for the brand. Returns null when: - Total views across the included videos are 0 - `estimatedCost` is `null` - No spend data is available for the platform
  - `content: array<object { contentId, title, publishTime, … 10 more }>`

    Performance data for one piece of this creator's sponsored content for the queried brand.

    - `contentId: string`

      Platform-specific content identifier (`videoId` for YouTube, `mediaId` for Instagram).
    - `title: string`

      Content title (for YouTube videos) or caption excerpt (for Instagram posts).
    - `publishTime: number`

      Publish time, represented as a Unix timestamp in milliseconds.
    - `views7d: number,null`

      Cumulative view count 7 days after publication. Returns `null` if fewer than 7 days have passed since publication.
    - `views30d: number,null`

      Cumulative view count 30 days after publication. Returns `null` if fewer than 30 days have passed since publication.
    - `views90d: number,null`

      Cumulative view count 90 days after publication. Returns `null` if fewer than 90 days have passed since publication.
    - `viewsLifetime: number`

      Total view count for this content piece since publication.
    - `likes: number`

      Like count for this content piece. Calculation may vary depending on platform and content age.
    - `comments: number`

      Comment count for this content piece. Calculation may vary depending on platform and content age.
    - `engagementRate: number`

      Engagement rate of this content piece. Expressed as a decimal and rounded to the 4th decimal place (e.g. 0.1202 = 12.02%).
    - `length: number,null`

      Video length in seconds. Returns `null` for non-video content.
    - `hashtags: array<string>`

      Hashtags used in this content.
    - `estimatedContentCPM: number,null`
- `totalResults: integer`

  Total number of creators that match the queried brand and platform, across all pages.
- `offset: integer`

  Offset applied to this response (matches the request offset).
- `pageSize: integer`

  Page size applied to this response (matches the request `pageSize`).

**Example response**

```json
{
  "data": {
    "sponsoredCreators": [
      {
        "creatorId": "UCm-X6o81nRsXQTmqpyArkBQ",
        "displayName": "Flamingo",
        "platform": "youtube",
        "creatorTotalStats": {
          "avgEngagementRate": 0.0452,
          "avgViews": 1600000,
          "avgLikes": 63700,
          "avgComments": 5200,
          "contentCount": 180,
          "latestContentDate": 1741939200000
        },
        "creatorAllSponsoredStats": {
          "avgEngagementRate": 0.0412,
          "avgViews": 1950000,
          "avgLikes": 66500,
          "avgComments": 5350,
          "sponsoredCount": 42,
          "latestSponsoredContentDate": 1738569600000
        },
        "creatorSpecificSponsoredStats": {
          "avgEngagementRate": 0.0379,
          "avgViews": 2200000,
          "avgLikes": 69800,
          "avgComments": 5500,
          "sponsoredCount": 3,
          "latestSponsoredContentDate": 1733529600000
        },
        "estimatedCost": 4500,
        "estimatedCreatorCPM": 9.12,
        "content": [
          {
            "contentId": "eHnzGYHEdO0",
            "title": "ROBLOX OP ADMIN IN STEAL A BRAINROT",
            "publishTime": 1754797869000,
            "views7d": 8200,
            "views30d": 15000,
            "views90d": 28500,
            "viewsLifetime": 150000,
            "likes": 10000,
            "comments": 100,
            "engagementRate": 0.1202,
            "length": 873,
            "hashtags": [
              "#VLOG"
            ],
            "estimatedContentCPM": 300
          }
        ]
      }
    ],
    "totalResults": 156,
    "offset": 0,
    "pageSize": 50
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /sponsor/list — List Brands

Source: https://docs.creatordb.app/api-reference/sponsor/list-brands.md
Credits: 1 per page

Returns a paginated brand directory for catalog synchronization, dropdowns, or audits. Does not support filters — use /sponsor/search for filtered queries. Includes each brand's total sponsored content count and the platforms where sponsored content has been detected.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `pageSize` | query | string | no |  |
| `offset` | query | string | no |  |
| `sortBy` | query | string | no |  |
| `desc` | query | string | no |  |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/sponsor/list" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `brands: array<object { brandId, name, logo, … 4 more }>`

  Brand summary records.

  - `brandId: string`

    Unique brand identifier.
  - `name: string`

    Brand's display name.
  - `logo: string`

    URL of the brand's logo.
  - `industries: array<string>`

    Industries the brand operates in.
  - `country: string`

    Headquarters country in ISO 3166-1 alpha-3 format (e.g., `USA`).
  - `sponsoringPlatforms: array<string>`

    Social media platforms where this brand has detected sponsored activity.
  - `totalSponsoredContent: integer`

    Total count of sponsored content pieces detected across the platforms in `sponsoringPlatforms`. Returns `0` when no sponsorships have been detected.
- `totalBrands: integer`

  Total number of brands in the database.
- `offset: integer`

  Offset applied to this response (matches the request offset).
- `pageSize: integer`

  Page size applied to this response (matches the request `pageSize`).

**Example response**

```json
{
  "data": {
    "brands": [
      {
        "brandId": "acer.com",
        "name": "Acer",
        "logo": "https://i.imgur.com/bazrFjP.png",
        "industries": [
          "Computer",
          "Consumer Electronics",
          "… 1 more items"
        ],
        "country": "TWN",
        "sponsoringPlatforms": [
          "YouTube",
          "Instagram"
        ]
      }
    ],
    "totalBrands": 10342,
    "offset": 0,
    "pageSize": 100
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### GET /sponsor/creators — List Sponsored Creators

Source: https://docs.creatordb.app/api-reference/sponsor/list-sponsored-creators.md
Credits: 25

Returns a paginated list of creators sponsored by a brand on a specified platform (YouTube or Instagram).

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `brandId` | query | string | yes |  |
| `platform` | query | string | yes |  |
| `pageSize` | query | string | no |  |
| `offset` | query | string | no |  |
| `sortBy` | query | string | no |  |
| `desc` | query | string | no |  |

**Request**

```bash
curl -X GET "https://apiv3.creatordb.app/sponsor/creators" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `creators: array<object { creatorId, platform, displayName, … 9 more }>`

  Returns a paginated list of creators sponsored by the queried brand on the specified platform (YouTube or Instagram).

  - `creatorId: string`

    Platform-specific creator identifier (`channelId` for YouTube, `uniqueId` for Instagram).
  - `platform: "youtube" | "instagram"`

    Platform for which this creator's sponsored activity was queried.
  - `displayName: string`

    Creator's display name.
  - `avatar: string`

    Creator's avatar URL.
  - `sponsoredContent: array<string>`

    URLs of this creator's sponsored content for the brand being queried.
  - `country: string`

    Creator's country in ISO 3166-1 alpha-3 format.
  - `followers: number`

    Creator's follower count (Instagram) or subscriber count (YouTube), depending on the queried platform.
  - `avgRecentSponsoredEngagementRate: number`

    Average engagement rate across this creator's recent sponsored content for the brand. Expressed as a decimal (e.g., 0.0452 = 4.52%), rounded to 4 decimal places.
  - `topics: array<string>`

    Creator's content topics.
  - `niches: array<string>`

    Creator's content niches.
  - `sponsoredCount: integer`

    Number of sponsored content pieces from this creator for the queried brand.
  - `lastSponsoredDate: integer`

    Unix timestamp (in milliseconds) of this creator's most recent sponsored content for the queried brand.
- `totalResults: integer`

  Total number of creators that match the queried brand and platform, across all pages.
- `offset: integer`

  Offset applied to this response (matches the request offset).
- `pageSize: integer`

  Page size applied to this response (matches the request `pageSize`).

**Example response**

```json
{
  "data": {
    "creators": [
      {
        "creatorId": "UCm-X6o81nRsXQTmqpyArkBQ",
        "platform": "youtube",
        "displayName": "Flamingo",
        "avatar": "https://yt3.ggpht.com/example",
        "sponsoredContent": [
          "https://www.youtube.com/watch?v=abc123"
        ],
        "country": "USA",
        "followers": 12000000,
        "avgRecentSponsoredEngagementRate": 0.0452,
        "topics": [
          "RPG"
        ],
        "niches": [
          "gaming_Gaming"
        ],
        "sponsoredCount": 3,
        "lastSponsoredDate": 1754797869000
      }
    ],
    "totalResults": 30,
    "offset": 0,
    "pageSize": 50
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": ""
}
```

### POST /sponsor/search — Search Brands

Source: https://docs.creatordb.app/api-reference/sponsor/search-brands.md
Credits: 2 per page

Search the CreatorDB sponsor database using filters including brand name, industry, region, and creator associations. Returns a brand list suitable for discovery; use `/sponsor/information` for detailed brand data. Supports fuzzy name search, ISO 3166-1 alpha-3 country codes, and pagination.

**Request body**

```json
{
  "filters": [
    {
      "filterName": "industry",
      "op": "in",
      "value": [
        "Computer",
        "ConsumerElectronics"
      ]
    },
    {
      "filterName": "sponsoringRegion",
      "op": "=",
      "value": "USA"
    }
  ],
  "desc": true,
  "sortBy": "name",
  "pageSize": 20,
  "offset": 0
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `results: array<object { brandId, name, logo, … 2 more }>`

  Brands matching the search query.

  - `brandId: string`

    Unique brand identifier, typically the brand's primary domain.
  - `name: string`

    Brand's display name.
  - `logo: string`

    URL of the brand's logo.
  - `industries: array<string>`

    Industries the brand operates in.
  - `country: string`

    Headquarters country in ISO 3166-1 alpha-3 format (e.g., `USA`).
- `totalResults: integer`

  Total number of brands matching the filters.
- `offset: integer`

  Offset applied to this response (matches the request offset).
- `pageSize: integer`

  Page size applied to this response (matches the request `pageSize`).

**Example response**

```json
{
  "data": {
    "results": [
      {
        "brandId": "acer.com",
        "name": "Acer",
        "logo": "https://i.imgur.com/bazrFjP.png",
        "industries": [
          "Computer",
          "Consumer Electronics"
        ],
        "country": "TWN"
      }
    ],
    "totalResults": 342,
    "offset": 0,
    "pageSize": 20
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorDescription": "",
  "success": true
}
```

### POST /sponsor/submit — Submit Brand

Source: https://docs.creatordb.app/api-reference/sponsor/submit-brand.md
Credits: —

Submits a brand for review and addition to the CreatorDB database. Submitted brands are not immediately available through other `/v3/sponsor` endpoints — each submission is reviewed before indexing. Each API key can make up to 100 submissions per day (resets at 00:00 UTC). The response `status` field returns one of: * `accepted` — The brand submission was accepted. * `done` — The brand is already indexed. The existing record ID is returned in `existingBrandId`.(No costs) * `rejected` — The submission was invalid or the brand is blacklisted.(No costs) For per submitted brand cost, see [API Credit Usage](/api-v3/api-credit-usage).

**Request body**

```json
{
  "brandName": "Notion",
  "brandUrl": "https://www.notion.so",
  "competitors": [
    "Odoo",
    "Everything App"
  ],
  "notes": "Frequently sponsors productivity and tech YouTube channels"
}
```

**Request**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/submit" \
  -H "api-key: <YOUR_API_KEY>"
```

**Response — `data` payload**

- `submissionId: string`

  Unique submission identifier for this submission.
- `status: "accepted" | "done" | "rejected"`

  The current status of the submission. One of: * `accepted` — The brand submission was accepted. Costs 1 credit. * `done` — The brand already exists in CreatorDB. The existing record ID is returned in `existingBrandId`. Costs 0 credits. * `rejected` — The submission was invalid or the brand is blacklisted. Costs 0 credits.
- `existingBrandId?: string,null`

  When `status` is `done`, the `brandId` of the existing brand in CreatorDB. `null` for all other statuses, and may also be `null` while the brand record is being prepared.

**Example response**

```json
{
  "data": {
    "submissionId": "69dc931e8015d8a4a41ad288",
    "status": "accepted",
    "existingBrandId": "notion.so"
  },
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4e3f2a1b0",
  "timestamp": 1750732453635,
  "creditsAvailable": 975,
  "creditsUsed": 25,
  "planCreditsAvailable": 900,
  "purchasedCreditsAvailable": 75,
  "keyCreditsAvailable": 4975,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```


# Part 3: Concepts

## Fractional calls

Source: https://docs.creatordb.app/api-v3/fractional-calls.md
Per-field and per-item cost tables: https://docs.creatordb.app/api-v3/field-and-item-costs.md

By default a CreatorDB data endpoint returns its full response and charges a fixed **full-bundle
price**. With **fractional calls** you request only the fields or items you need and pay
proportionally. You are **never charged more than the full-bundle price** — the cap is absolute,
so enumerating many fields can never cost more than asking for everything.

**Prerequisite:** Fractional Calls must be enabled on the API key. If it is not, any request that
includes `fields` returns `400` with `errorCode: FractionalCallsNotEnabled`. Full-bundle calls
(no `fields`) always work. The fix is to omit `fields`, not to retry the same request. Contact your
account manager to enable it.

### Method rule

An endpoint is `POST` **if and only if** it accepts a `fields` parameter. The 17 fractional
endpoints take their identifier (`channelId` or `uniqueId`) in the JSON **body**, not the query
string:

| Platform | Fractional endpoints (`POST`) |
| --- | --- |
| YouTube | `profile`, `contact`, `performance`, `audience`, `content-detail`, `sponsorship` |
| Instagram | `profile`, `contact`, `performance`, `audience`, `content-detail`, `sponsorship` |
| TikTok | `profile`, `contact`, `performance`, `audience`, `content-detail` (no `sponsorship`) |

Still `GET`, and they do **not** accept `fields`: `usage`, `performance-history` (all platforms),
`topics`, `niches`, `subtitles/meta`, `subtitles/download`, and every `sponsor/*` read endpoint.

### The `fields` parameter by endpoint type

| Endpoint type | Endpoints | `fields` shape | Billing |
| --- | --- | --- | --- |
| Field-list | `profile`, `performance`, `audience`, `contact` | `array<string>` of field names | sum of per-field costs, capped at full bundle |
| Per-item | `content-detail`, `sponsorship` | `object` mapping an array field to an item count | per item / per brand, capped at full bundle |
| Range | `performance-history` | not accepted — `400` in any shape | set by `pastDayRange` (3–5) |
| Search enrichment | `search` | `object` keyed by bare endpoint name | per enrichment, **per result returned** |

Field-list endpoints reject an **object**; per-item endpoints reject an **array**, including the
legacy `["recentVideos:5"]` form. Both return `400`.

Passing no `fields`, `fields: []` (field-list), or `fields: {}` (per-item) are all equivalent and
bill the full-bundle price.

### Per-item costs

- `content-detail`: `0.1` credits per content item (video, short, image, or reel). Full bundle 3.
- `sponsorship`: `0.5` credits per sponsoring brand. Full bundle 5. YouTube and Instagram only.

### Search enrichment

On `/{platform}/search`, `fields` does not subset search's own return fields — it enriches each
result with data from other endpoints on the same platform, billed per result returned. Keys must
be bare endpoint names (`profile`, not `youtube/profile`); a key containing `/` returns `400`.
Because cost multiplies by result count, lower `pageSize` to control spend. `performance-history`
enrichment always requires `pastDayRange`. See the per-platform search sections in Part 2.

### Examples

```bash
# Two profile fields — well under the 2-credit full bundle
curl -X POST "https://apiv3.creatordb.app/youtube/profile" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{"channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "fields": ["displayName", "country"]}'

# Five recent videos — 0.1 x 5 = 0.5 credits (full bundle would be 3)
curl -X POST "https://apiv3.creatordb.app/youtube/content-detail" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{"channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA", "fields": {"recentVideos": 5}}'

# Full response at the full-bundle price — omit fields entirely
curl -X POST "https://apiv3.creatordb.app/youtube/profile" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API-KEY_HERE>" \
  -d '{"channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA"}'
```

### Agent guidance

- Prefer search enrichment over search-then-loop. One call with `fields` beats N+1 per-creator calls.
- Read `creditsUsed` as a float — fractional billing returns values like `0.4` or `3.04`.
- Only fall back to per-creator enrichment endpoints when the creator list came from outside a
  search (e.g. a user-supplied list of IDs), since there is nothing to enrich inline.
- `nls` does not support fractional field selection in this release; it stays token-based.

## Custom search filters

CreatorDB's custom search filters support fuzzy search. Filter configurations and examples for each platform are documented below.

### YouTube

#### Configuring Custom YouTube Filter Search Criteria

**Method**: `POST` <br />
**Description**: Search for YouTube creators based on custom filter criteria such as `displayName`, subscriber count, video performance, and more.

**Important: Request Parameter Limits**
- **Filter Count**: Maximum **10** filter objects per request.
- **Array Value Limit**: When using the `in` operator, the array can contain a maximum of **100** string values.
- **Page Size**: The upper limit for `pageSize` is **100**.
- **Fuzzy Search**: `isFuzzySearch: true` is only available for **String** type fields.

##### Request Parameters

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **filters** | `object[]` | Yes | An array of filter objects that includes: `filterName`, `op`, and `value`. |
| └ `filterName` | `string` | Yes | The field to apply the filter on. |
| └ `op` | `string` | Yes | The comparison operator.<br />- String fields support: `=`, `in`<br />• Number fields support: `>`, `=`, `<`<br />• Boolean fields support: `=` |
| └ `value` | `string`<br />`number`<br />`string[]`<br />`boolean`| Yes | The filter value. The type depends on the `filterName`.<br />For `in` operator, provide `string[]`.|
| └ `isFuzzySearch` | `boolean` | No | Default `false`. When set to `true`, the filter will perform a fuzzy match. **Only applicable for string-type fields.** |
| **desc** | `boolean` | No | Default `false` (Ascending). Set to `true` for descending order. |
| **sortBy** | `string` | No | Field used to sort results. See table below for supported fields. |
| **pageSize** | `number` | Yes | Specifies the maximum number of results to return. **Max 100**. |
| **offset** | `number` | Yes | Indicates the number of records to skip before starting to return results. |

##### Available `filterName` & `sortBy`

| Filter Name | Type | Supported Operators | Can be `SortBy` | Description |
| :--- | :--- | :--- | :--- | :--- |
| **displayName** | `string` | `=`, `in` | ✅ Yes | The name of the YouTube channel. |
| **uniqueId** | `string` | `=`, `in` | ✅ Yes | The YouTube username/handle.<br />**Constraint**: Must be 3-100 characters, allowing letters, numbers, dots, hyphens, and underscores. Can include optional `@` prefix (e.g., `mrbeast` or `@mrbeast`). |
| **mainCategory** | `string` | `=`, `in` | ✅ Yes | The primary category of the channel's content. |
| **country** | `string` | `=`, `in` | ✅ Yes | The country associated with the channel.<br />**Constraint**: Must be in **ISO 3166-1 alpha-3** format (e.g., `TWN`, `USA`). |
| **mainLanguage** | `string` | `=`, `in` | ✅ Yes | The main language of the channel's videos.<br />**Constraint**: Must be in **ISO 639-3** format.|
| **languages** | `string` | `=`, `in` | ✅ Yes | All languages used in the channel's videos.<br />**Constraint**: Must be in **ISO 639-3** format. |
| **secondLanguage** | `string` | `=`, `in` | ✅ Yes | The secondary language used in the channel's videos.<br />**Constraint**: Must be in **ISO 639-3** format. |
| **hashtags** | `string` | `=`, `in` | ❌ No | Keywords/tags used in video descriptions or tags. |
| **niches** | `string` | `=`, `in` | ❌ No | Represents unified content theme identified by CreatorDB's AI model. |
| **topics** | `string` | `=`, `in` | ❌ No | YouTube specific topics associated with the channel. |
| **mainAudienceLocation**| `string` | `=`, `in` | ✅ Yes | The country where the channel's audience is most concentrated.<br />**Constraint**: Must be in **ISO 3166-1 alpha-3** format. |
| **mainAudienceAge** | `string` | `=`, `in` | ✅ Yes | The primary age range of the channel's audience.<br />**Allowed Values**: `"13-17"`, `"18-24"`, `"25-34"`, `"35-44"`, `"45-54"`, `"55-64"`, `"65+"`.|
| **mainAudienceGender** | `string` | `=`, `in` | ❌ No | The dominant gender group among the channel's audience.<br />**Allowed Values**: `"male"`, `"female"`. |
| **totalSubscribers** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of subscribers. |
| **totalContents** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of videos uploaded by the creator. |
| **totalViews** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of views across all videos. |
| **lastPublishTime** | `number` | `>`, `=`, `<` | ✅ Yes | The timestamp of the most recent video upload (Unix timestamp in milliseconds). |
| **subscriberGrowthIn30d**| `number` | `>`, `=`, `<` | ✅ Yes | The growth rate of subscribers in the past 30 days. |
| **avgRecentVideosLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Average likes per video (based on recent long-form videos). |
| **avgVideosLikesAll** | `number` | `>`, `=`, `<` | ✅ Yes | Average likes per video (based on all-time long-form videos). |
| **medianRecentVideosLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Median likes per video (based on recent long-form videos). |
| **medianVideosLikesAll** | `number` | `>`, `=`, `<` | ✅ Yes | Median likes per video (based on all-time long-form videos). |
| **avgRecentVideosComments**| `number` | `>`, `=`, `<` | ✅ Yes | Average comments per video (based on recent long-form videos). |
| **avgVideosCommentsAll** | `number` | `>`, `=`, `<` | ✅ Yes | Average comments per video (based on all-time long-form videos). |
| **avgRecentVideosViews**| `number` | `>`, `=`, `<` | ✅ Yes | Average views per video (based on recent long-form videos). |
| **avgVideosViewsAll** | `number` | `>`, `=`, `<` | ✅ Yes | Average views per video (based on all-time long-form videos). |
| **medianRecentVideosViews**| `number` | `>`, `=`, `<` | ✅ Yes | Median views per video (based on recent long-form videos). |
| **medianVideosViewsAll** | `number` | `>`, `=`, `<` | ✅ Yes | Median views per video (based on all-time long-form videos). |
| **avgRecentVideosEngagementRate**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate for recent long-form videos. Calculated as `(likes + comments) / subscribers`. |
| **avgVideosEngagementRateAll**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate for all-time long-form videos. |
| **avgRecentShortsViews**| `number` | `>`, `=`, `<` | ✅ Yes | Average views per short (based on recent shorts). |
| **avgShortsViewsAll** | `number` | `>`, `=`, `<` | ✅ Yes | Average views per short (based on all-time shorts). |
| **medianRecentShortsViews**| `number` | `>`, `=`, `<` | ✅ Yes | Median views per short (based on recent shorts). |
| **medianShortsViewsAll** | `number` | `>`, `=`, `<` | ✅ Yes | Median views per short (based on all-time shorts). |
| **avgRecentShortsLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Average likes per short (based on recent shorts). |
| **avgShortsLikesAll** | `number` | `>`, `=`, `<` | ✅ Yes | Average likes per short (based on all-time shorts). |
| **medianRecentShortsLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Median likes per short (based on recent shorts). |
| **medianShortsLikesAll** | `number` | `>`, `=`, `<` | ✅ Yes | Median likes per short (based on all-time shorts). |
| **avgRecentShortsComments**| `number` | `>`, `=`, `<` | ✅ Yes | Average comments per short (based on recent shorts). |
| **avgShortsCommentsAll** | `number` | `>`, `=`, `<` | ✅ Yes | Average comments per short (based on all-time shorts). |
| **avgRecentShortsEngagementRate**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate for recent shorts. Calculated as `(likes + comments) / subscribers`. |
| **avgShortsEngagementRateAll**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate for all-time shorts. |
| **avgRecentContentsViews**| `number` | `>`, `=`, `<` | ✅ Yes | Average views across all content types (Videos + Shorts) in recent posts. |
| **avgRecentContentsLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Average likes across all content types (Videos + Shorts) in recent posts. |
| **avgRecentContentsComments**| `number` | `>`, `=`, `<` | ✅ Yes | Average comments across all content types (Videos + Shorts) in recent posts. |
| **avgRecentContentsEngagementRate**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate across all content types in recent posts. |
| **avgRecentContentsViewsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average views across all content types in recent posts. |
| **avgRecentContentsLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes across all content types in recent posts. |
| **avgRecentContentsCommentsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average comments across all content types in recent posts. |
| **avgRecentContentsEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate across all content types in recent posts. |
| **avgRecentVideosViewsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average views per long-form video in recent posts. |
| **avgRecentVideosLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes per long-form video in recent posts. |
| **avgRecentVideosCommentsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average comments per long-form video in recent posts. |
| **avgRecentVideosEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate per long-form video in recent posts. |
| **avgRecentShortsViewsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average views per short in recent posts. |
| **avgRecentShortsLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes per short in recent posts. |
| **avgRecentShortsCommentsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average comments per short in recent posts. |
| **avgRecentShortsEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate per short in recent posts. |
| **subscriberCountPercentile**| `number` | `>`, `=`, `<` | ✅ Yes | Percentile ranking of subscriber count compared to all YouTube channels (0-100). |
| **avgContentViewsPercentile**| `number` | `>`, `=`, `<` | ✅ Yes | Percentile ranking of average content views compared to all YouTube channels (0-100). |
| **avgContentEngagementPercentile**| `number` | `>`, `=`, `<` | ✅ Yes | Percentile ranking of average content engagement compared to all YouTube channels (0-100). |
| **subscriberCountPercentileGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of subscriber count percentile ranking. |
| **avgContentViewsPercentileGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average content views percentile ranking. |
| **avgContentEngagementPercentileGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average content engagement percentile ranking. |
| **platformScore** | `number` | `>`, `=`, `<` | ✅ Yes | CreatorDB proprietary platform score indicating overall influence. |
| **joinedDate** | `number` | `>`, `=`, `<` | ✅ Yes | The timestamp when the channel was created (Unix timestamp in milliseconds). |
| **contentsIn30Days** | `number` | `>`, `=`, `<` | ✅ Yes | Number of videos published in the last 30 days. |
| **contentsIn90Days** | `number` | `>`, `=`, `<` | ✅ Yes | Number of videos published in the last 90 days. |
| **audienceMaleRatio** | `number` | `>`, `=`, `<` | ✅ Yes | The percentage of male subscribers in the channel's audience (0-100). |
| **audienceFemaleRatio** | `number` | `>`, `=`, `<` | ✅ Yes | The percentage of female subscribers in the channel's audience (0-100). |
| **hasSponsors** | `boolean`| `=` | ❌ No | Indicates whether the channel has published sponsored content. |

#### Using Subscribers as a YouTube Filter Search Criteria

The examples below demonstrate some common YouTube subscriber filter configurations.

By default, CreatorDB will list search results in descending order.

##### Filtering subscribers with a minimum value

By specifying greater than (`>` ) as the operation value, you can search for YouTube creators with a minimum number of subscribers. The following example will search the CreatorDB database for ten creators with at least 100,000 subscribers and list their YouTube ID in descending order.

**Request example**

```json
curl --request POST \
  --url https://apiv3.creatordb.app/youtube/search \
  --header 'Content-Type: application/json' \
  --header 'api-key: <<YOUR_API_KEY>>' \
  --data '
{
  "filters": [
    {
      "filterName": "totalSubscribers",
      "op": ">",
      "value": "100000",
      "isFuzzySearch": true
    }
  ],
  "pageSize": 10,
  "offset": 0,
  "desc": true,
  "sortBy": "totalSubscribers"
}
'
```

**Response example**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "🪐🌍Gallivud_prod",
        "uniqueId": "@gallivud_prod",
        "channelId": "UCMS8ONu5i0tKTyZ4_lLD1DA",
        "avatarUrl": "https://yt3.googleusercontent.com/geeG3ok-_7PzCBlXDEW8Ro2m0QNl_XRH4AekEVvPqBhgmrFJbn2iKzn06lSnI2GnkybvaJY7=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1400000
      },
      {
        "displayName": "🪐MILENA MARS🪐",
        "uniqueId": "@milenamars",
        "channelId": "UCjTWFYn4s7fzsonX3Jtw_Ig",
        "avatarUrl": "https://yt3.googleusercontent.com/kFfAtp8wQM5wTqRzFn1wiZWdcJ5atGU1u-BnzpadbVFQJBThObAYNZTxsagdHnzW5m79G5A4pg=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 2170000
      },
      {
        "displayName": "🩷La Barbie Jimenez 🩷",
        "uniqueId": "@labarbiejimenez",
        "channelId": "UC2Z5u_Azat1RoqK-7-Sy4Tg",
        "avatarUrl": "https://yt3.googleusercontent.com/h6_4n7pOk4AAn93qpxZl0abQZjYtg4PtzxXnsPO3l4wF7p3d8271Q_F_TqeUDsvuQKA6aIPaxYo=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1050000
      },
      {
        "displayName": "🦋wishkhanna_🦋",
        "uniqueId": "@wishkhanna____",
        "channelId": "UC32P0rFNpMhz97Oast8Mdgg",
        "avatarUrl": "https://yt3.googleusercontent.com/rubd3-FNnl6pEpm5po_t6J67FE0IV_p452ujgAlxs1QITLGzi-nObStp06dbR3Qz96RJ5gm1=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1450000
      },
      {
        "displayName": "🥜𝐀𝐧𝐲𝐚 𝐂𝐡𝐚𝐧🥜",
        "uniqueId": "@yandere79",
        "channelId": "UCVYsu-OqwXh9wF9eHERXcNg",
        "avatarUrl": "https://yt3.googleusercontent.com/kOFqPM33m-b9YLSSjS499UciWpwZMJ0-MLmTjycnBUoGr3OCF2-yH8lMrT4VDgi4XznVX7TA9w=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 2250000
      },
      {
        "displayName": "🤍cloudy express 🤍",
        "uniqueId": "@cloudyexpress-cb3pf",
        "channelId": "UCo7-sHv2yP_tk2FFbfwmILQ",
        "avatarUrl": "https://yt3.googleusercontent.com/c5pVxWtJhkU12B3D_MS_pfEV-9wpwyxsCHHrOLP67tEQgAf5uNwreDaPHxIqIqS81LIRbjX8w8A=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1030000
      },
      {
        "displayName": "🙏Jay shri shyam🙏",
        "uniqueId": "@bhaktisagar609",
        "channelId": "UC2e-a4J25uO7Vqdz5s9D39w",
        "avatarUrl": "https://yt3.googleusercontent.com/1onewDKzTDXArcN-SSOogr_-eGczRvnWi2jlcxMGaxSJq9e8DDMgFwfs7BpaXogQwfFt2Cm3=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1810000
      },
      {
        "displayName": "🙏 Pray Together 🙏",
        "uniqueId": "@frastefano",
        "channelId": "UCEISS2bKsVnyvPSGvK-q_mg",
        "avatarUrl": "https://yt3.googleusercontent.com/lqbSpiP1yWva-3v1pbFlZ--tVLaQJuCwGP1vvoAi75-w-VqJe0QDzUxqtfwUfE25Qem15nxy3w=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1270000
      },
      {
        "displayName": "🖤BRK",
        "uniqueId": "@mr.say3ed",
        "channelId": "UCCQ7XwHCZetFk0zJWadP1Ww",
        "avatarUrl": "https://yt3.googleusercontent.com/kr5zTRyltQF-7K7iCIiB9iMV1wOmvpRPYvUeIqa_KdxmzRwAe_FdEiS7heUG7bTJLibMP7HHUg=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1160000
      },
      {
        "displayName": "🖤 everytime BTS 🖤",
        "uniqueId": "@everytimebts2517",
        "channelId": "UCEi2lZb1oSZ7tDP5vi4U9tg",
        "avatarUrl": "https://yt3.googleusercontent.com/YGNUzzRXD7hvz6Swqgs-NR7sZGiuKodJr15sLdf4tYPMyVXvw3M2ZTN9RJ3psNn5sHmJ3dhxxw=s900-c-k-c0x00ffffff-no-rj",
        "totalSubscribers": 1110000
      }
    ],
    "hasNextPage": true,
    "nextOffset": 10
  },
  "quotaUsed": 1,
  "quotaUsedTotal": 1,
  "remainingQuota": -1,
  "traceId": "f3430ba969f51fc42d633cb4fd00f86d",
  "timestamp": 1767923571340,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

##### Filtering subscribers with a maximum value

By specifying less than (`<` ) as the operation value, you can search for YouTube creators with a maximum number of subscribers. The following example will search the CreatorDB database for ten creators with less than 10,000 subscribers and list their YouTube ID in descending order.

**Request example**

```json
curl --request POST \
  --url https://apiv3.creatordb.app/youtube/search \
  --header 'Content-Type: application/json' \
  --header 'api-key: <<YOUR_API_KEY>>' \
  --data '
{
  "filters": [
    {
      "filterName": "totalSubscribers",
      "op": "<",
      "value": "10000",
      "isFuzzySearch": true
    }
  ],
  "pageSize": 10,
  "offset": 0,
  "desc": true,
  "sortBy": "totalSubscribers"
}
'
```

**Response example**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "<string>",
        "uniqueId": "<string>",
        "channelId": "<string>",
        "avatarUrl": "<string>",
        "totalSubscribers": 1
      }
    ],
    "hasNextPage": true,
    "nextOffset": 1
  },
  "traceId": "<string>",
  "timestamp": 123,
  "errorCode": "<string>",
  "errorDescription": "<string>",
  "success": true
}
```

##### Filtering subscribers within a range

You can specify the range in advanced search filters by using the filter operations greater than (`>`) and less than (`<`). For example, the request sample below will return ten YouTube IDs with 10,000 to 100,000 subscribers.

**Request example**

```json
  curl --request POST \
  --url https://apiv3.creatordb.app/youtube/search \
  --header 'Content-Type: application/json' \
  --header 'api-key: <<YOUR_API_KEY>>' \
  --data '
{
  "filters": [
    {
      "filterName": "totalSubscribers",
      "op": ">",
      "value": "10000",
      "isFuzzySearch": true
    },
    {
      "filterName": "totalSubscribers",
      "op": "<",
      "value": "100000",
      "isFuzzySearch": true
    }
  ],
  "pageSize": 10,
  "offset": 0,
  "desc": true,
  "sortBy": "displayName"
}
'
```

**Response example**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "<string>",
        "uniqueId": "<string>",
        "channelId": "<string>",
        "avatarUrl": "<string>",
        "totalSubscribers": 1
      }
    ],
    "hasNextPage": true,
    "nextOffset": 1
  },
  "traceId": "<string>",
  "timestamp": 123,
  "errorCode": "<string>",
  "errorDescription": "<string>",
  "success": true
}
```

#### Using Average Views as a YouTube Filter Search Criteria
CreatorDB provides several average views filter options for YouTube videos and shorts. 

| Type | Filters |
| :--- |  :---  |
| **Videos and shorts combined** |`avgRecentContentsViews`, `avgRecentContentsViewsGrowth`, `avgContentViewsPercentile`, `avgContentViewsPercentileGrowth` |
| **Videos** |`avgVideosViewsAll`, `avgRecentVideosViews`, `avgRecentVideosViewsGrowth`  |
| **Shorts** |`avgShortsViewsAll`, `avgRecentShortsViews`, `avgRecentShortsViewsGrowth` |

##### Filtering by `avgVideosViewsAll` with a minimum value

Use the `>`  operator to search for YouTube creators with a minimum average view count for up to 800 videos uploaded in the past year. For example, the API request below finds ten creators with at least 10,000 average YouTube video views in the last year and lists their YouTube IDs in descending order of channel subscribers.
**Request example**

```json
curl --request POST \
  --url https://apiv3.creatordb.app/youtube/search \
  --header 'Content-Type: application/json' \
  --header 'api-key: <<YOUR_API_KEY>>' \
  --data '
{
  "filters": [
    {
      "filterName": "avgVideosViewsAll",
      "op": ">",
      "value": "10000",
      "isFuzzySearch": true
    }
  ],
  "pageSize": 10,
  "offset": 0,
  "desc": true,
  "sortBy": "totalSubscribers"
}
'
```

**Response example**

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "<string>",
        "uniqueId": "<string>",
        "channelId": "<string>",
        "avatarUrl": "<string>",
        "totalSubscribers": 1
      }
    ],
    "hasNextPage": true,
    "nextOffset": 1
  },
  "traceId": "<string>",
  "timestamp": 123,
  "errorCode": "<string>",
  "errorDescription": "<string>",
  "success": true
}
```

### Instagram

#### Configuring Custom Instagram Filter Search Criteria

**Method**: `POST` <br />
**Description**: Search for Instagram creators based on custom filter criteria such as `displayName`, follower count, content performance, and more.

**Important: Request Parameter Limits**
- **Filter Count**: Maximum **10** filter objects per request.
- **Array Value Limit**: When using the `in` operator, the array can contain a maximum of **100** string values.
- **Page Size**: The upper limit for `pageSize` is **100**.
- **Fuzzy Search**: `isFuzzySearch: true` is only available for **String** type fields.

##### Request Parameters

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **filters** | `object[]` | Yes | An array of filter objects that includes: `filterName`, `op`, and `value`. |
| └ `filterName` | `string` | Yes | The field to apply the filter on. |
| └ `op` | `string` | Yes | The comparison operator.<br />• String fields support: `=`, `in`<br />• Number fields support: `>`, `=`, `<`<br />• Boolean fields support: `=` |
| └ `value` | `string`<br />`number`<br />`string[]`<br />`boolean` | Yes | The filter value. The type depends on the `filterName`.<br />For `in` operator, provide `string[]`. |
| └ `isFuzzySearch` | `boolean` | No | Default `false`. When set to `true`, the filter will perform a fuzzy match. **Only applicable for string-type fields.** |
| **desc** | `boolean` | No | Default `false` (Ascending). Set to `true` for descending order. |
| **sortBy** | `string` | No | Field used to sort results. See table below for supported fields. |
| **pageSize** | `number` | Yes | Specifies the maximum number of results to return. **Max 100**. |
| **offset** | `number` | Yes | Indicates the number of records to skip before starting to return results. |

##### Available `filterName` & `sortBy`

| Filter Name | Type | Supported Operators | Can be `SortBy` | Description |
| :--- | :--- | :--- | :--- | :--- |
| **displayName** | `string` | `=`, `in` | ✅ Yes | The display name set by the creator. |
| **uniqueId** | `string` | `=`, `in` | ✅ Yes | The Instagram username/handle.<br />**Constraint**: Must be 1-30 characters, allowing letters, numbers, dots, and underscores. Can include optional `@` prefix (e.g., `cristiano` or `@cristiano`). |
| **category** | `string` | `=`, `in` | ✅ Yes | Account category defined by creators with professional accounts.|
| **country** | `string` | `=`, `in` | ✅ Yes | The country associated with the creator.<br />**Constraint**: Must be in **ISO 3166-1 alpha-3** format (e.g., `TWN`, `USA`).|
| **mainLanguage** | `string` | `=`, `in` | ✅ Yes | The main language used in the creator's posts.<br />**Constraint**: Must be in **ISO 639-3** format. |
| **languages** | `string` | `=`, `in` | ✅ Yes | All languages used in the creator's posts.<br />**Constraint**: Must be in **ISO 639-3** format. |
| **secondLanguage** | `string` | `=`, `in` | ✅ Yes | The secondary language used in the creator's posts.<br />**Constraint**: Must be in **ISO 639-3** format.|
| **hashtags** | `string` | `=`, `in` | ❌ No | Keyword used by the creator in their post captions or descriptions. |
| **niches** | `string` | `=`, `in` | ❌ No | Represents unified content theme identified by CreatorDB's AI model. |
| **taggedCreator** | `string` | `=`, `in` | ❌ No | The Instagram handle to search for. Returns creators who have tagged this handle in their posts. |
| **relatedCreator** | `string` | `=`, `in` | ❌ No | The Instagram handle to base the lookalike search on. Returns creators recommended by Instagram algorithms. |
| **mainAudienceLocation**| `string` | `=`, `in` | ✅ Yes | The country where the creator's audience is most concentrated.<br />**Constraint**: Must be in **ISO 3166-1 alpha-3** format.|
| **mainAudienceAge** | `string` | `=`, `in` | ✅ Yes | The primary age range of the creator's audience.<br />**Allowed Values**: `"13-17"`, `"18-24"`, `"25-34"`, `"35-44"`, `"45-54"`, `"55-64"`, `"65+"`.|
| **mainAudienceGender** | `string` | `=`, `in` | ❌ No | The dominant gender group among the creator's audience.<br />**Allowed Values**: `"male"`, `"female"`.|
| **totalFollowers** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of users who follow the creator. |
| **following** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of other Instagram accounts that the creator is following. |
| **totalContents** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of posts uploaded by the creator. |
| **lastPublishTime** | `number` | `>`, `=`, `<` | ✅ Yes | The timestamp of the creator's most recent content upload (Unix timestamp in milliseconds). |
| **followerGrowthIn30d**| `number` | `>`, `=`, `<` | ✅ Yes | The growth rate of the creator's follower count in the past 30 days. |
| **avgRecentImagesLikes**| `number` | `>`, `=`, `<` | ✅ Yes | The average number of likes per image post (based on recent posts). |
| **medianRecentImagesLikes**| `number` | `>`, `=`, `<` | ✅ Yes | The median number of likes received on recent image posts. |
| **avgRecentImagesComments**| `number` | `>`, `=`, `<` | ✅ Yes | The average number of comments per image post (based on recent posts). |
| **avgRecentImagesEngagementRate**| `number`| `>`, `=`, `<`| ✅ Yes | The average engagement rate per image post. Calculated as `(likes + comments) / followers`. |
| **avgRecentReelsViews** | `number` | `>`, `=`, `<` | ✅ Yes | The average number of views per reel (based on recent reels). |
| **medianRecentReelsViews**| `number` | `>`, `=`, `<` | ✅ Yes | The median number of views received on recent reels. |
| **avgRecentReelsLikes** | `number` | `>`, `=`, `<` | ✅ Yes | The average number of likes per reel (based on recent reels). |
| **medianRecentReelsLikes**| `number` | `>`, `=`, `<` | ✅ Yes | The median number of likes received on recent reels. |
| **avgRecentReelsComments**| `number` | `>`, `=`, `<` | ✅ Yes | The average number of comments per reel (based on recent reels). |
| **avgRecentReelsEngagementRate**| `number`| `>`, `=`, `<` | ✅ Yes | The average engagement rate per reel. Calculated as `(likes + comments) / followers`. |
| **avgRecentContentsLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Average likes across all content types (Images + Reels) in recent posts. |
| **avgRecentContentsComments**| `number`| `>`, `=`, `<` | ✅ Yes | Average comments across all content types (Images + Reels) in recent posts. |
| **avgRecentContentsEngagementRate**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate across all content types in recent posts. |
| **avgRecentContentsLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes across all content types in recent posts. |
| **avgRecentContentsCommentsGrowth**| `number`| `>`, `=`, `<` | ✅ Yes | Growth rate of average comments across all content types in recent posts. |
| **avgRecentContentsEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate across all content types in recent posts. |
| **avgRecentReelsViewsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average views per reel in recent posts. |
| **avgRecentReelsLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes per reel in recent posts. |
| **avgRecentReelsCommentsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average comments per reel in recent posts. |
| **avgRecentReelsEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate per reel in recent posts. |
| **avgRecentImagesLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes per image in recent posts. |
| **avgRecentImagesCommentsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average comments per image in recent posts. |
| **avgRecentImagesEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate per image in recent posts. |
| **contentsIn30Days** | `number` | `>`, `=`, `<` | ✅ Yes | The number of total contents published in the last 30 days. |
| **imagesIn30Days** | `number` | `>`, `=`, `<` | ✅ Yes | The number of image posts published in the last 30 days. |
| **reelsIn30Days** | `number` | `>`, `=`, `<` | ✅ Yes | The number of reels published in the last 30 days. |
| **platformScore** | `number` | `>`, `=`, `<` | ✅ Yes | CreatorDB proprietary platform score indicating overall influence. |
| **imageLastPublishTime**| `number` | `>`, `=`, `<` | ✅ Yes | Timestamp of the most recent image post (Unix timestamp in milliseconds). |
| **reelsLastPublishTime**| `number` | `>`, `=`, `<` | ✅ Yes | Timestamp of the most recent reel post (Unix timestamp in milliseconds). |
| **audienceMaleRatio** | `number` | `>`, `=`, `<` | ✅ Yes | The percentage of male followers in the creator's audience (0-100). |
| **audienceFemaleRatio** | `number` | `>`, `=`, `<` | ✅ Yes | The percentage of female followers in the creator's audience (0-100). |
| **hasSponsors** | `boolean`| `=` | ❌ No | Indicates whether the creator has published sponsored contents. |
| **isAccountVerified** | `boolean`| `=` | ❌ No | Indicates if the account has a verified badge (blue check). |

### TikTok

#### Configuring Custom TikTok Filter Search Criteria

**Method**: `POST` <br />
**Description**: Search for TikTok creators based on custom filter criteria such as `displayName`, follower count, content performance, and more.
**Important: Request Parameter Limits**
- **Filter Count**: Maximum **10** filter objects per request.
- **Array Value Limit**: When using the `in` operator, the array can contain a maximum of **100** string values.
- **Page Size**: The upper limit for `pageSize` is **100**.
- **Fuzzy Search**: `isFuzzySearch: true` is only available for **String** type fields.

##### Request Parameters

| Name | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **filters** | `object[]` | Yes | An array of filter objects that includes: `filterName`, `op`, and `value`. |
| └ `filterName` | `string` | Yes | The field to apply the filter on. |
| └ `op` | `string` | Yes | The comparison operator.• String fields support: `=`, `in`<br />• Number fields support: `>`, `=`, `<`<br />• Boolean fields support: `=` |
| └ `value` | `string`<br />`number` <br />`string[]`<br />`boolean`| Yes | The filter value. The type depends on the `filterName`.<br />For `in` operator, provide `string[]`. |
| └ `isFuzzySearch` | `boolean` | No | Default `false`. When set to `true`, the filter will perform a fuzzy match. **Only applicable for string-type fields.** |
| **desc** | `boolean` | No | Default `false` (Ascending). Set to `true` for descending order. |
| **sortBy** | `string` | No | Field used to sort results. See table below for supported fields. |
| **pageSize** | `number` | Yes | Specifies the maximum number of results to return. **Max 100**. |
| **offset** | `number` | Yes | Indicates the number of records to skip before starting to return results. |

##### Available `filterName` & `sortBy`

| Filter Name | Type | Supported Operators | Can be `SortBy` | Description |
| :--- | :--- | :--- | :--- | :--- |
| **displayName** | `string` | `=`, `in` | ✅ Yes | The display name set by the creator. |
| **uniqueId** | `string` | `=`, `in` | ✅ Yes | The TikTok username/handle.<br />**Constraint**: Must be 1-100 characters, allowing letters, numbers, dots, hyphens, and underscores. Can include optional `@` prefix (e.g., `charlidamelio` or `@charlidamelio`). |
| **category** | `string` | `=`, `in` | ✅ Yes | Account category. |
| **country** | `string` | `=`, `in` | ✅ Yes | The country associated with the creator.<br />**Constraint**: Must be in **ISO 3166-1 alpha-3** format (e.g., `TWN`, `USA`). |
| **mainLanguage** | `string` | `=`, `in` | ✅ Yes | The main language used in the creator's videos.<br />**Constraint**: Must be in **ISO 639-3** format.|
| **languages** | `string` | `=`, `in` | ✅ Yes | All languages used in the creator's videos.<br />**Constraint**: Must be in **ISO 639-3** format. |
| **secondLanguage** | `string` | `=`, `in` | ✅ Yes | The secondary language used in the creator's videos.<br />**Constraint**: Must be in **ISO 639-3** format. |
| **hashtags** | `string` | `=`, `in` | ❌ No | Keywords used in video captions. |
| **niches** | `string` | `=`, `in` | ❌ No | Represents unified content theme identified by CreatorDB's AI model. |
| **mainAudienceLocation**| `string` | `=`, `in` | ✅ Yes | The country where the creator's audience is most concentrated.<br />**Constraint**: Must be in **ISO 3166-1 alpha-3** format. |
| **mainAudienceAge** | `string` | `=`, `in` | ✅ Yes | The primary age range of the creator's audience.<br />**Allowed Values**: `"13-17"`, `"18-24"`, `"25-34"`, `"35-44"`, `"45-54"`, `"55-64"`, `"65+"`. |
| **mainAudienceGender** | `string` | `=`, `in` | ❌ No | The dominant gender group among the creator's audience.<br />**Allowed Values**: `"male"`, `"female"`. |
| **totalFollowers** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of followers. |
| **following** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of other TikTok accounts that the creator is following. |
| **totalContents** | `number` | `>`, `=`, `<` | ✅ Yes | The total number of videos uploaded. |
| **lastPublishTime** | `number` | `>`, `=`, `<` | ✅ Yes | The timestamp of the most recent video upload (Unix timestamp in milliseconds). |
| **followerGrowthIn30d**| `number` | `>`, `=`, `<` | ✅ Yes | The growth rate of followers in the past 30 days. |
| **avgRecentVideosLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Average likes per video (based on recent videos). |
| **medianRecentVideosLikes**| `number` | `>`, `=`, `<` | ✅ Yes | Median likes per video (based on recent videos). |
| **avgRecentVideosComments**| `number` | `>`, `=`, `<` | ✅ Yes | Average comments per video (based on recent videos). |
| **avgRecentVideosViews**| `number` | `>`, `=`, `<` | ✅ Yes | Average views per video (based on recent videos). |
| **medianRecentVideosViews**| `number` | `>`, `=`, `<` | ✅ Yes | Median views per video (based on recent videos). |
| **avgRecentVideosShares**| `number` | `>`, `=`, `<` | ✅ Yes | Average shares per video (based on recent videos). |
| **avgRecentVideosEngagementRate**| `number`| `>`, `=`, `<`| ✅ Yes | Average engagement rate per video. Calculated as `(likes + comments + shares) / followers`. |
| **avgRecentVideosEngagementRateGrowth**| `number`| `>`, `=`, `<`| ✅ Yes | Growth rate of average engagement rate per video in recent posts. |
| **avgRecentVideosLikesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average likes per video in recent posts. |
| **avgRecentVideosCommentsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average comments per video in recent posts. |
| **avgRecentVideosSharesGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average shares per video in recent posts. |
| **avgRecentVideosViewsGrowth**| `number` | `>`, `=`, `<` | ✅ Yes | Growth rate of average views per video in recent posts. |
| **contentsIn30Days** | `number` | `>`, `=`, `<` | ✅ Yes | Number of videos published in the last 30 days. |
| **platformScore** | `number` | `>`, `=`, `<` | ✅ Yes | CreatorDB proprietary platform score indicating overall influence. |
| **audienceMaleRatio** | `number` | `>`, `=`, `<` | ✅ Yes | The percentage of male followers in the creator's audience (0-100). |
| **audienceFemaleRatio** | `number` | `>`, `=`, `<` | ✅ Yes | The percentage of female followers in the creator's audience (0-100). |
| **isAccountVerified** | `boolean`| `=` | ❌ No | Indicates if the account has a verified badge. |
| **isPrivateAccount** | `boolean`| `=` | ❌ No | Indicates if the account is set to private. |

### Sponsor

#### Sponsor Search Filters

##### Overview
CreatorDB supports searching for brands that have sponsored YouTube or Instagram creators with predefined filters, such as brand name, industry, region, creator partnerships, estimated spend, and more. When making the API call, you can specify which predefined filters you'd like to add to your search using the `POST` methods. By default, search results are listed by total sponsored content in ascending order.

**Important: Request Parameter Limits**
- **Filter Count**: Maximum **10** filter objects per request.
- **Array Value Limit**: When using the `in` operator, the array can contain a maximum of **100** string values.
- **Page Size**: The upper limit for `pageSize` is **100**.
- **Fuzzy Search**: `isFuzzySearch: true` is only available for **String** type fields.

##### API Call Flow

1. Use the **Sponsor Search API** to find brands that have sponsored creators on YouTube or Instagram, based on the specified filter conditions. You can filter brands by name, headquarters location, and YouTube or Instagram ID.

2. Use the brand name from calling the **Sponsor List API** to get detailed brand information and performance metrics of their sponsored creators on YouTube and Instagram.

You will be charged 2 API credits for every 10 filter objects included in a single request. For example, 1–10 filters \= 2 credit, 11–20 filters \= 4 credits, and so on.

##### Request Parameters

| Name | Type | Required | Example | Description |
| :--- | :--- | :--- | :--- | :--- |
| **filters** | `object[]` | Yes |  | An array of filter objects that includes: `filterName`, `op`, and `value`. If empty, returns unfiltered results sorted by default configurations. |
| └ `filterName` | `string` | Yes | `country` | The field to apply the filter on. |
| └ `op` | `string` | Yes | `=` | The comparison operator.<br />• String fields support: `=`, `in`<br />• Number fields support: `>`, `=`, `<`<br />• Boolean fields support: `=` |
| └ `value` | `string`<br />`number` <br />`string[]`<br />`boolean`| Yes | `USA` |The filter value. The type depends on the `filterName`. For `in` operator, provide `string[]`.|
| └ `isFuzzySearch` | `boolean` | No | `true` |Default `false`. When set to `true`, the filter will perform a fuzzy match. **Only applicable for string-type fields.** |
| **desc**     | `boolean` | No | `true` |Default `false` (Ascending). Set to `true` for descending order. |
| **sortBy** | `string` | No | `name`|Field used to sort results. Supported values are: `name`, `totalSponsoredContent`, `estimatedTotalSpend7d`, `estimatedTotalSpend30d`, `estimatedTotalSpend90d`. If omitted, the default is relevance when query is provided; otherwise the default is`totalSponsoredContent`. |
| **pageSize** | `number` | Yes | 100 | The number of results to return per page. By default, will return 100 results. |
| **offset** | `number` | Yes | 0|The number of records to skip before starting to return results. Default is 0. |

##### Available `filterName` & `sortBy`

The table below lists the available `filterName` options for the **Sponsor Search API**. Each entry includes the expected data types, an example value, and indicates whether the field supports sorting. When the **Supports sorting** column is checkmarked, that field can also be used as a `sortBy` parameter to sort search results in ascending or descending order.

The sorting behavior depends on the data type — for example, strings are sorted alphabetically.

| Filter Name | Type | Supported Operators | Example | Definition | Supports sorting |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **name** | `string` or `string[]` | `in`, `=` | `Acer` | The brand name or alias. Set `isFuzzySearch` to `true` for fuzzy matching. | ✅ Yes |
| **industry** | `string` or `string[]` | `in`, `=` | `["Computer", "ConsumerElectronics"]` | Filter brands by one or multiple industries. For details, see [Industry List](api-v3/industry-list.mdx). | ❌ No |
| **country** | `string` or `string[]` | `in`, `=` | `USA` | The country the brand is headquartered in, in **ISO 3166-1 alpha-3** format. For details, see [Country Codes](api-v2/country-code.mdx). | ❌ No |
| **sponsoringRegion** | `string` or `string[]` | `in`, `=` | `USA` | The country where the brand's sponsored creators are primarily located, in **ISO 3166-1 alpha-3** format. For details, see [Country Codes](api-v2/country-code.mdx). | ❌ No |
| **sponsoredYoutubeCreatorId** | `string` or `string[]` | `in`, `=` | `UCm-X6o81nRsXQTmqpyArkBQ` | Returns brands that have sponsored the specified YouTube creator. Accepts YouTube channelId. | ❌ No |
| **sponsoredInstagramCreatorId** | `string` or `string[]` | `in`, `=` | `mrbeast` | Returns brands that have sponsored the specified Instagram creator. Accepts Instagram handles and is not case sensitive. | ❌ No |
| **sponsoringPlatform** | `string` or `string[]` | `in`, `=` | `youtube` | Returns brands that have sponsorships on the specified social media platform. Valid values are: `youtube`, `instagram`. | ❌ No |
| **hasActiveCampaign** | `boolean` | `=` | `true` | Indicates whether the brand has published sponsored content in the last 30 days. | ❌ No |

##### Using the Creator as a Filter in Sponsor Search

The following examples demonstrate how to use a creator's platform ID as a filter to retrieve corresponding sponsored information and to query detailed sponsorship performance reports across Instagram and YouTube. You need to enter the creator's YouTube channel ID or Instagram handle information..

By default, CreatorDB lists search results by the brand's total sponsored content in ascending order.

###### Filtering by `sponsoredYoutubeCreatorId` using a single value

By specifying the `sponsoredYoutubeCreatorId` filter with a YouTube channel ID `UCm-X6o81nRsXQTmqpyArkBQ`, you can retrieve a list of brands that have sponsored this specific YouTube creator. This allows you to analyze the creator's sponsorship landscape and identify potential brand partnerships.

**Request example**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "filters": [
        {
            "filterName": "sponsoredYoutubeCreatorId",
            "op": "=",
            "value": "UCm-X6o81nRsXQTmqpyArkBQ"
        }
    ],
    "pageSize": 20,
    "offset": 0
}'
```

**Response example**

```json
    {
  "data": {
    "results": [
      {
        "brandId": "redmagic.gg",
        "name": "Red Magic",
        "logo": "https://i.imgur.com/zxuo5yf.jpeg",
        "industries": [
          "Gaming",
          "Consumer Electronics"
        ],
        "country": "CHN"
      },
      {
        "brandId": "opera.com",
        "name": "Opera",
        "logo": "https://i.imgur.com/btAsAE9.png",
        "industries": [
          "Information Technology",
          "Internet",
          "Mobile",
          "Software"
        ],
        "country": "NOR"
      },
      {
        "brandId": "msi.com",
        "name": "Micro Star International - MSI",
        "logo": "https://i.imgur.com/OASiwxr.png",
        "industries": [
          "Hardware",
          "Manufacturing"
        ],
        "country": "TWN"
      },
      {
        "brandId": "infinitynikki.infoldgames.com",
        "name": "Infold Games",
        "logo": "https://i.imgur.com/o1UEYod.png",
        "industries": [
          "Video Games",
          "Software",
          "Human Computer Interaction",
          "Digital Media",
          "Consumer Electronics"
        ],
        "country": "CHN"
      },
      {
        "brandId": "geoguessr.com",
        "name": "GeoGuessr",
        "logo": "https://i.imgur.com/RdHIhGY.png",
        "industries": [
          "Digital Entertainment",
          "Gaming"
        ],
        "country": "SWE"
      },
      {
        "brandId": "epicgames.com",
        "name": "Epic Games",
        "logo": "https://i.imgur.com/rE9OaJl.png",
        "industries": [
          "Gaming",
          "Software",
          "Metaverse",
          "Digital Entertainment"
        ],
        "country": "USA"
      }
    ],
    "totalResults": 6,
    "offset": 0,
    "pageSize": 20
  },
  "traceId": "68d377fc9259e2d8f75f2ccf090b9152",
  "timestamp": 1776223842261,
  "creditsAvailable": 999985,
  "creditsUsed": 2,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

###### Filtering by `sponsoredInstagramCreatorId` using multiple values

By specifying `in` as the operation value, you can search for multiple Instagram creators at the same time. For example, by entering `abby.neff` and `adrianpeachy` in the `sponsoredInstagramCreatorId` filter, you can retrieve a list of brands that have sponsored either of these two popular Instagram creators. This allows you to compare the sponsorship landscapes of multiple creators and identify common brand partnerships or unique sponsors associated with each creator.

**Request example**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "filters": [
        {
            "filterName": "sponsoredInstagramCreatorId",
            "op": "in",
            "value": ["abby.neff", "adrianpeachy"]
        }
    ],
    "pageSize": 20,
    "offset": 0
}'
```

**Response example**

```json
   {
  "data": {
    "results": [
      {
        "brandId": "shop.lululemon.com",
        "name": "Lululemon",
        "logo": "https://i.imgur.com/Z9yAIdQ.png",
        "industries": [
          "Wellness",
          "E-Commerce",
          "Fitness",
          "Lifestyle"
        ],
        "country": "CAN"
      }
    ],
    "totalResults": 1,
    "offset": 0,
    "pageSize": 20
  },
  "traceId": "864b0045464ccd9481b6e82b5dbdfa85",
  "timestamp": 1776232799131,
  "creditsAvailable": 999973,
  "creditsUsed": 2,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

##### Using the Brand Name as a Filter in Sponsor Search

The following examples demonstrate how to use a competitor's brand name as a filter to retrieve the brand's information and industry.
By default, CreatorDB lists search results by the brand's total sponsored content in ascending order.

###### Filtering by `name` using a single value

By using the equals operator (`=`), you can specify which brand data to retrieve from the CreatorDB database.

**Request example**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "filters": [
        {
            "filterName": "name",
            "op": "=",
            "value": "Adidas"
        }
    ],
    "pageSize": 20,
    "offset": 0
}'
```

**Response example**

```json
   {
  "data": {
    "results": [
      {
        "brandId": "adidas.com",
        "name": "Adidas",
        "logo": "https://i.imgur.com/4Ha4wep.jpeg",
        "industries": [
          "Sporting Goods",
          "Fashion",
          "Fitness",
          "Lifestyle",
          "Manufacturing",
          "Marketing"
        ],
        "country": "DEU"
      }
    ],
    "totalResults": 1,
    "offset": 0,
    "pageSize": 20
  },
  "traceId": "e0d460deb8bea46c1754d91bda92621a",
  "timestamp": 1776224442114,
  "creditsAvailable": 999979,
  "creditsUsed": 2,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

###### Filtering by `name` using multiple values

By using the `in` operator, you can specify multiple brand names to retrieve information for several brands at once. This allows you to quickly gather data on multiple competitors and compare their sponsorship activities and industries.

**Request example**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "filters": [
        {
            "filterName": "name",
            "op": "in",
            "value": ["Adidas", "Puma", "Nike"]
        }
    ],
    "pageSize": 20,
    "offset": 0
}'
```

**Response example**

```json
  {
  "data": {
    "results": [
      {
        "brandId": "puma.com",
        "name": "Puma",
        "logo": "https://i.imgur.com/d7susAe.png",
        "industries": [
          "Sporting Goods",
          "Fashion",
          "Shoes"
        ],
        "country": "DEU"
      },
      {
        "brandId": "nike.com",
        "name": "Nike",
        "logo": "https://i.imgur.com/lQxXmgm.jpeg",
        "industries": [
          "Sporting Goods",
          "E-Commerce",
          "Shoes",
          "Consumer Goods"
        ],
        "country": "USA"
      },
      {
        "brandId": "adidas.com",
        "name": "Adidas",
        "logo": "https://i.imgur.com/4Ha4wep.jpeg",
        "industries": [
          "Sporting Goods",
          "Fashion",
          "Fitness",
          "Lifestyle",
          "Manufacturing",
          "Marketing"
        ],
        "country": "DEU"
      }
    ],
    "totalResults": 3,
    "offset": 0,
    "pageSize": 20
  },
  "traceId": "05761611befed14aad3eb523e5b2f8f9",
  "timestamp": 1776237890929,
  "creditsAvailable": 999971,
  "creditsUsed": 2,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

##### Using Multiple Filters to Narrow Brand Search Results
The following example demonstrates how you can use multiple filters, such as `industry`, `sponsoringRegion`, and `sponsoredInstagramCreatorId`, to narrow the brand search results to find only the most relevant sponsors. In this example, the search results will return up to 20 brands in the ecommerce industry that have sponsored primarily US-based creators. Sponsor search currently only supports Instagram and YouTube data.
 
 **Request example**

```bash
curl -X POST "https://apiv3.creatordb.app/sponsor/search" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "filters": [
        {
            "filterName": "industry",
            "op": "in",
            "value": ["E-Commerce"]
        },
        {
            "filterName": "sponsoringRegion",
            "op": "=",
            "value": "USA"
        },
        {
            "filterName": "sponsoredInstagramCreatorId",
            "op": "=",
            "value": "10eegaming"
        }
    ],
    "pageSize": 20,
    "offset": 0,
    "sortBy": "name",
    "desc": true
}'
```

**Response example**

```json
    {
      "data":{
        "results":[
          {
            "brandId":"temu.com",
            "name":"Temu",
            "logo":"https://i.imgur.com/E2Pd6gR.jpeg",
            "industries":["E-Commerce","E-Commerce Platforms"],
            "country":"USA"
          }
          ],
          "totalResults":1,
          "offset":0,
          "pageSize":20,
          "traceId":"6f1ab2aa720148a680d713885b660b4c",
          "timestamp":1776222865822,
          "creditsAvailable":999987,
          "creditsUsed":2,
          "errorCode":"",
          "errorDescription":"",
          "success":true
      } 
```

## Natural language search

Search for creators by describing what you're looking for in plain language. The CreatorDB API converts your description into structured search filters and returns matching creators.

### How it works

Send a `POST` request to `/nls` with a `description` field. The AI analyzes your query, determines the appropriate platform (YouTube, Instagram, or TikTok), and returns matching creators.

You don't need to specify a platform — the API detects it from your query. For example, "YouTube gaming creators with 1M subscribers" automatically searches YouTube, while "Instagram fashion influencers in Japan" searches Instagram.

NLS uses Server-Sent Events (SSE) streaming. You'll receive progress updates as the query is processed, followed by the final results.

### Endpoint

```http
POST https://apiv3.creatordb.app/nls
```

#### Request body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `description` | string | Yes | A natural language description of the creators you're looking for (1–1000 characters). |

#### Headers

| Header | Value |
|--------|-------|
| `Content-Type` | `application/json` |
| `api-key` | Your API key |

### Streaming response

The response is delivered as a stream of Server-Sent Events (SSE). Each event has a type and a JSON data payload.

#### Progress events

While the query is being processed, you'll receive progress updates:

```text
event: progress
data: {"message": "Analyzing your query..."}

event: progress
data: {"message": "Searching for creators..."}
```

#### Result event — creator results

When matching creators are found, the final event contains the results:

```text
event: result
data: {
  "data": {
    "creatorList": [
      {
        "displayName": "James Charles",
        "uniqueId": "@jamescharles",
        "channelId": "UCucot-Zp428OwkyRm2I7v2Q",
        "avatarUrl": "https://yt3.googleusercontent.com/...",
        "totalSubscribers": 24000000
      }
    ],
    "platform": "youtube"
  },
  "creditsUsed": 3,
  "creditsAvailable": 997,
  "traceId": "02a03542233eff21e4a781c9a5090e18",
  "timestamp": 1770099403116,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

The `platform` field tells you which platform the AI selected based on your query.

#### Result event — suggestions

If your query is too broad or ambiguous, the API returns suggestions instead of results:

```text
event: result
data: {
  "data": {
    "message": "Your query is too broad to return specific results. Try narrowing your search.",
    "suggestion": [
      "Try: US-based beauty YouTubers with over 1M subscribers",
      "Try: Instagram fashion influencers in Japan with 500K+ followers",
      "Try: TikTok comedy creators with high engagement rates"
    ]
  },
  "creditsUsed": 1,
  "creditsAvailable": 999,
  "traceId": "a1b2c3d4e5f6",
  "timestamp": 1770099403116,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### Credit cost

NLS uses dynamic, token-based pricing. The cost depends on the complexity of your query and the AI processing required. Typical queries cost 2–4 credits.

### Examples

#### Find YouTube beauty creators

```bash
curl -X POST "https://apiv3.creatordb.app/nls" \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "description": "Find US-based YouTube beauty creators that own makeup brands and have more than 15 million subscribers"
  }'
```

**Response** (final result event):

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "James Charles",
        "uniqueId": "@jamescharles",
        "channelId": "UCucot-Zp428OwkyRm2I7v2Q",
        "avatarUrl": "https://yt3.googleusercontent.com/...",
        "totalSubscribers": 24000000
      },
      {
        "displayName": "Troom Troom",
        "uniqueId": "@troomtroom",
        "channelId": "UCWwqHwqLSrdWMgp5DZG5Dzg",
        "avatarUrl": "https://yt3.googleusercontent.com/...",
        "totalSubscribers": 23900000
      }
    ],
    "platform": "youtube"
  },
  "creditsUsed": 3,
  "creditsAvailable": 997,
  "traceId": "02a03542233eff21e4a781c9a5090e18",
  "timestamp": 1770099403116,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

#### Find Instagram sustainable fashion influencers

```bash
curl -X POST "https://apiv3.creatordb.app/nls" \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "description": "Looking for Instagram fashion influencers who focus on sustainable clothing, with at least 500K followers, primarily targeting female audiences aged 18-24 in the USA"
  }'
```

**Response** (final result event):

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "THE ZERO WASTE GUIDE by Allott",
        "uniqueId": "thezerowasteguide",
        "avatarUrl": "https://scontent.cdninstagram.com/...",
        "totalFollowers": 709115
      },
      {
        "displayName": "Sophie Webb",
        "uniqueId": "what.sophie.does",
        "avatarUrl": "https://scontent.cdninstagram.com/...",
        "totalFollowers": 987172
      }
    ],
    "platform": "instagram"
  },
  "creditsUsed": 4,
  "creditsAvailable": 993,
  "traceId": "f8e4a3b2c1d0e9f8a7b6c5d4",
  "timestamp": 1770099503200,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

#### Find TikTok cooking creators

```bash
curl -X POST "https://apiv3.creatordb.app/nls" \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "description": "TikTok cooking creators in Korea who make short recipe videos with over 2 million followers"
  }'
```

**Response** (final result event):

```json
{
  "data": {
    "creatorList": [
      {
        "displayName": "Recipe Example",
        "uniqueId": "recipeexample",
        "avatarUrl": "https://p16-sign.tiktokcdn.com/...",
        "totalFollowers": 2500000
      }
    ],
    "platform": "tiktok"
  },
  "creditsUsed": 2,
  "creditsAvailable": 991,
  "traceId": "c4d5e6f7a8b9c0d1",
  "timestamp": 1770099603300,
  "errorCode": "",
  "errorDescription": "",
  "success": true
}
```

### Tips for better queries

- **Be specific about the platform** — include "YouTube", "Instagram", or "TikTok" in your query for faster, more accurate results.
- **Include measurable criteria** — subscriber/follower thresholds, engagement rates, or content frequency give the AI concrete filters to apply.
- **Describe the audience** — specifying audience demographics (age, gender, location) helps narrow results.
- **Mention content themes** — terms like "tech review", "sustainable fashion", or "cooking tutorials" help the AI classify the niche.
- **Keep queries under a few sentences** — concise descriptions work better than long paragraphs. The maximum is 1000 characters.

NLS returns a maximum of 20 creators per query. For larger result sets, use the [search endpoint](/api-v3/configuring_advanced_search_filters) with structured filters.

## Error codes

CreatorDB communicates request status through HTTP response codes. A response in the **2xx** range means the request was successful, while a **4xx** response suggests an error caused by invalid credentials, insufficient API credits, or missing parameters. A response in the **5xx** range indicates an error on the server side, which may be temporary. If you encounter a **5xx** error, please try your request again later. If the issue persists, contact CreatorDB support for assistance. 

### Error types and HTTP status codes

The following table shows the different error `types` based on the status code of the HTTP response:

| HTTP STATUS CODE | ERROR `TYPE` | DESCRIPTION                                                                                                                                                                      |
| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400              | `VALIDATION ERROR` | This request is invalid or a validation error occurred. Check the `details` field in the response for more information about the specific errors.                          |
| 401              | `UNAUTHORIZED` | This request is unauthorized. This error occurs when the API key is missing or invalid. Please check the API key in the request header and make sure it is correct.            |
| 403              | `FORBIDDEN`  | This request is authenticated but the user does not have permission to access the requested resource. Check your API key permissions and ensure you are authorized to access the requested data. |
| 404              | `NOT FOUND`  | The requested resource could not be found. This error occurs when the specified endpoint or resource does not exist. Verify the endpoint URL and parameters in your request.     |
| 409              | `CONFLICT`   | This request could not be completed due to a conflict with the current state of the resource. This error may occur when there are duplicate entries or conflicting data in the request. Check the request data for any conflicts and try again. |
| 429              | `QUOTA EXCEEDED` | The request rate limit or quota has been exceeded. This error occurs when you have made too many requests in a short period of time. Please wait and try again later.        |
| 500              | `INTERNAL SERVER ERROR` | An unexpected error occurred on the server. This error may occur due to temporary issues or maintenance. Please try again later. If the issue persists, contact CreatorDB support for assistance. |
| 503              | `SERVICE UNAVAILABLE` | The server is currently unavailable. This error may occur due to temporary database or upstream service issues or maintenance. Please try again later. If the issue persists, contact CreatorDB support for assistance. |


# Part 4: Appendices

## Credit costs

The amount of API credits charged per call may be subject to change in the final release of API 3.0.

The following table shows the API credits required for calling the different CreatorDB endpoints. Make sure you have sufficient API credits before making an API call. You can purchase additional API credits by contacting our sales team at sales@creatordb.app.

Values in the **Full-bundle credits** column are what you pay for the complete response. Endpoints
with a value in **Fractional pricing** can cost less when you request a subset via `fields`, capped
at the full-bundle price. See Part 3 → Fractional calls.

| Endpoint | Full-bundle credits | Fractional pricing | Notes |
| --- | --- | --- | --- |
| /nls | Dynamic (token-based) | No | Cost varies based on token usage |
| youtube/search | 1 | Enrichment only, per result | *For every 10 filters* |
| youtube/profile | 2 | Per field | |
| youtube/performance | 2 | Per field | |
| youtube/performance-history | 3–5 | No. Priced by `pastDayRange` | See Performance history pricing below |
| youtube/audience | 10 | Per field | |
| youtube/contact | 15 | Per field | |
| youtube/content-detail | 3 | `0.1` per item | |
| youtube/content-search | 25 | No | *Observed from response examples* |
| youtube/sponsorship | 5 | `0.5` per brand | |
| youtube/submitCreators | 1 per accepted creator | No | `0` for already-indexed or rejected |
| youtube/topics | 1 | No | |
| youtube/niches | 1 | No | |
| youtube/subtitles/meta | 1 | No | |
| youtube/subtitles/download | 3 | No | |
| instagram/search | 1 | Enrichment only, per result | *For every 10 filters* |
| instagram/profile | 2 | Per field | |
| instagram/performance | 2 | Per field | |
| instagram/performance-history | 3–5 | No. Priced by `pastDayRange` | See Performance history pricing below |
| instagram/audience | 10 | Per field | |
| instagram/contact | 15 | Per field | |
| instagram/content-detail | 3 | `0.1` per item | |
| instagram/content-search | 25 | No | *Observed from response examples* |
| instagram/sponsorship | 5 | `0.5` per brand | |
| instagram/submitCreators | 1 per accepted creator | No | `0` for already-indexed or rejected |
| instagram/niches | 1 | No | |
| tiktok/search | 1 | Enrichment only, per result | *For every 10 filters* |
| tiktok/profile | 2 | Per field | |
| tiktok/performance | 1.5 | Per field | |
| tiktok/performance-history | 3–5 | No. Priced by `pastDayRange` | See Performance history pricing below |
| tiktok/audience | 10 | Per field | |
| tiktok/contact | 15 | Per field | |
| tiktok/content-detail | 3 | `0.1` per item | |
| tiktok/content-search | 25 | No | *Observed from response examples* |
| tiktok/submitCreators | 1 per accepted creator | No | `0` for already-indexed or rejected |
| tiktok/niches | 1 | No | |
| sponsor/search | 2 | No | *For every 1 page* |
| sponsor/list | 1 | No | *For every 1 page* |
| sponsor/information | 2 | No | |
| sponsor/summary | 15 | No | |
| sponsor/creators | 15 | No | |
| sponsor/performance | 15 | No | |
| sponsor/audience | 15 | No | |
| sponsor/submit | 1 | No | |

### Performance history pricing

`performance-history` does not accept `fields`. Price is set solely by `pastDayRange`:

| `pastDayRange` | Credits |
| --- | --- |
| 1–7 days | 3 |
| 8–30 days | 3.5 |
| 31–90 days | 4 |
| 91–180 days | 4.5 |
| 181–365 days | 5 |

## Country codes
ISO 3166-1 alpha-3. Full table: https://docs.creatordb.app/api-v2/country-code.md

## Industry list
~770 entries. Full list: https://docs.creatordb.app/api-v2/industry-list.md

## Language codes

CreatorDB's API uses ISO three-letter lowercase abbreviations as the language values in the API request body. The following table lists the language codes supported by CreatorDB for advanced filter searches in alphabetic order.
|Language code            | Language                    |
|------------------------ | ----------------------------|
| afr                     | Afrikaans                   |
| amh                     | Amharic                     |
| ara                     | Arabic                      |
| asm                     | Assamese                    |
| aym                     | Aymara                      |
| aze                     | Azerbaijani                 |
| bam                     | Bambara                     |
| ban                     | Balinese                    |
| bel                     | Belarusian                  |
| ben                     | Bengali                     |
| bul                     | Bulgarian                   |
| ces                     | Czech                       |
| dan                     | Danish                      |
| deu                     | German                      |
| eli                     | Greek                       |
| eng                     | English                     |
| est                     | Estonian                    |
| fas                     | Persian                     |
| fil                     | Filipino                    |
| fin                     | Finnish                     |
| fra                     | French                      |
| ful                     | Fulah                       |
| gle                     | Irish                       |
| grn                     | Guarani                     |
| guj                     | Gujarati                    |
| hat                     | Haitian                     |
| hau                     | Hausa                       |
| hbs                     | Serbo-Croatian              |
| heb                     | Hebrew                      |
| hin                     | Hindi                       |
| hmn                     | Hmong                       |
| hne                     | Chhattisgarhi               |
| hun                     | Hungarian                   |
| hye                     | Armenian                    |
| isl                     | Icelandic                   |
| ita                     | Italian                     |
| jav                     | Javanese                    |
| jpn                     | Japanese                    |
| kab                     | Kabyle                      |
| kan                     | Kannada                     |
| kat                     | Georgian                    |
| kau                     | Kanuri                      |
| kaz                     | Kazakh                      |
| khm                     | Khmer                       |
| kin                     | Kinyarwanda                 |
| kir                     | Kirghiz                     |
| kok                     | Konkani                     |
| kor                     | Korean                      |
| kur                     | Kurdish                     |
| lao                     | Lao                         |
| lav                     | Latvian                     |
| lin                     | Lingala                     |
| lit                     | Lithuanian                  |
| lmo                     | Lombo                       |
| mad                     | Madurese                    |
| mal                     | Malayalam                   |
| mar                     | Marathi                     |
| mkd                     | Macedonian                  |
| mig                     | Malagasy                    |
| mong                    | Mongolian                   |
| mos                     | Mossi                       |
| msa                     | Malay                       |
| mya                     | Burmese                     |
| nap                     | Neapolitan                  |
| nep                     | Nepali                      |
| nld                     | Dutch                       |
| nor                     | Norwegian                   |
| nya                     | Nyanja                      |
| ori                     | Oriya                       |
| orm                     | Oromo                       |
| pan                     | Punjabi                     |
| pol                     | Polish                      |
| por                     | Portuguese                  |
| pus                     | Pashto                      |
| que                     | Quechua                     |
| rom                     | Romani                      |
| ron                     | Romanian                    |
| run                     | Rundi                       |
| rus                     | Russian                     |
| sag                     | Sango                       |
| sco                     | Scots                       |
| sin                     | Sinhala                     |
| slk                     | Slovak                      |
| slv                     | Slovenian                   |
| sna                     | Shona                       |
| som                     | Somali                      |
| spa                     | Spanish                     |
| sqi                     | Albanian                    |
| ssw                     | Swati                       |
| sun                     | Sundanese                   |
| swa                     | Swahili                     |
| swe                     | Swedish                     |
| tam                     | Tamil                       |
| tat                     | Tatar                       |
| tel                     | Telugu                      |
| tgk                     | Tajik                       |
| tha                     | Thai                        |
| tir                     | Tigrinya                    |
| tuk                     | Turkmen                     |
| tur                     | Turkish                     |
| ukr                     | Ukrainian                   |
| urd                     | Urdu                        |
| uzb                     | Uzbek                       |
| vie                     | Vietnamese                  |
| wes                     | Cameroon Pidgin             |
| wol                     | Wolof                       |
| xho                     | Xhosa                       |
| yor                     | Yoruba                      |
| zhs                     | Chinese (Simplified)        |
| zht                     | Chinese (Traditional)       |
| zul                     | Zulu                        |

## YouTube channel categories

By default, creators will assign a category to their YouTube channel out of pre-defined categories to help viewers find their content. These YouTube-defined categories can be used as search criteria or filters in the CreatorDB database to help you narrow the search scope and find relevant creators quickly. The following list contains all the accepted `mainCategory` values in alphabetical order:

- Autos & Vehicles
- Comedy
- Education
- Entertainment
- Film & Animation
- Gaming
- Howto & Style
- Music
- News & Politics
- Nonprofits & Activism
- Pets & Animals
- People & Blogs
- Science & Technology
- Sports
- Travel & Events

## Instagram categories

The Instagram categories are self-defined by creators and are not cleaned or maintained by CreatorDB. Therefore, there may be duplicates, misspellings, or similar categories with different names in the database. We recommend using the Instagram categories as reference and applying the Instagram `niches` filters to further narrow down your search results.

Creators can assign and name categories to their Instagram accounts to make finding them easier for interested businesses. Note that the categories are case-sensitive, and fuzzy search is not supported. For details, see [Configuring Custom Search Filters and Examples](https://docs.creatordb.app/api-v3/configuring_advanced_search_filters). The following list displays the top 1,000 commonly used Instagram categories that are supported by CreatorDB database in descending alphabetical order.

### A

\- ABORTION\_SERVICES  
\- Academic Camp  
\- Accessories  
\- ACCESSORIES\_STORE  
\- Addiction service  
\- ADDICTION\_SERVICE  
\- ADOPTION\_SERVICE  
\- ADVERTISING\_AGENCY  
\- ADVERTISING\_MARKETING  
\- African Restaurant  
\- AIDS resource centre  
\- Air quality monitoring site  
\- Aircraft Dealership  
\- Airline company  
\- Airline industry service  
\- Allergist  
\- Alternative & holistic health service  
\- Alto singer  
\- Amateur Sports Team  
\- American restaurant  
\- AMPHITHEATER  
\- Amphitheater  
\- Anaesthetist  
\- ANESTHESIOLOGISTS  
\- Animal Shelter  
\- ANIMAL\_RESCUE\_SERVICE  
\- Animals  
\- Animation studio  
\- APARTMENT\_CONDO\_BUILDING  
\- App Page  
\- App page  
\- Apparel Distributor  
\- Appliance Manufacturer  
\- Appliance repair service  
\- APPLIANCE\_MANUFACTURER  
\- Aquatic pet shop  
\- Arboretum  
\- ARCHERY  
\- ARGENTINE\_RESTAURANT  
\- Arranger  
\- Art  
\- Art Gallery  
\- Art Restoration Service  
\- Art school  
\- Art tour agency  
\- Arts & entertainment  
\- Arts & Humanities Website  
\- Arts & humanities website  
\- ARTS\_SITE  
\- Asian art museum  
\- ASIAN\_FUSION\_RESTAURANT  
\- Astrologist  
\- Astrologist & Psychic  
\- Astrologist and psychic  
\- ATHLETE  
\- Auction House  
\- Audio-visual equipment shop  
\- Australian Restaurant  
\- AUSTRALIAN\_RESTAURANT  
\- Automotive Glass Service  
\- Automotive Parts Store  
\- Automotive Restoration Service  
\- AUTOMOTIVE\_DEALERSHIP  
\- AUTOMOTIVE\_PARTS\_ACCESSORIES  
\- Aviation repair station  
\- AWNINGS\_CANOPIES

### B

\- Baby goods/children's goods  
\- Baby goods/kids goods  
\- Backing vocalist  
\- Bagel Shop  
\- BAGS\_LUGGAGE\_STORE  
\- BAKERY  
\- Bankruptcy Lawyer  
\- Bar & Grill  
\- BAR\_GRILL  
\- Barbecue restaurant  
\- Barber  
\- BARBER\_SHOP  
\- Barber's  
\- Bartending service  
\- BASEBALL\_FIELD  
\- BASEBALL\_STADIUM  
\- Basketball arena  
\- Basketball court  
\- Basketball Court  
\- BASKETBALL\_STADIUM  
\- Bass guitarist  
\- Bass Singer  
\- Bavarian restaurant  
\- Bavarian Restaurant  
\- BAVARIAN\_RESTAURANT  
\- Beach  
\- BEACH\_RESORT  
\- Beatboxer  
\- Beauty supplier  
\- Beauty Supplier  
\- Bed and Breakfast  
\- BED\_AND\_BREAKFAST  
\- Beer garden  
\- BEIJING\_RESTAURANT  
\- BETTING\_SHOP  
\- Bike trail  
\- BIKE\_RENTAL\_BIKE\_SHARE  
\- Bingo hall  
\- BINGO\_HALL  
\- Biographer  
\- Biotechnology company  
\- BIZ\_SITE  
\- Blinds and curtains shop  
\- Block of flats  
\- Blogger  
\- Board Game  
\- Board game  
\- Boat Rental  
\- BOAT\_RENTAL  
\- BOOK\_MAGAZINE\_DISTRIBUTION  
\- Books & Magazines  
\- Botanical garden  
\- Bottled Water Supplier  
\- BOTTLED\_WATER\_COMPANY  
\- BOXING\_STUDIO  
\- BRAND  
\- Brazilian Restaurant  
\- Breakfast & brunch restaurant  
\- Bridal Shop  
\- BROADCASTING\_MEDIA\_PRODUCTION  
\- BUFFET\_RESTAURANT  
\- Building Material Store  
\- Burger restaurant  
\- Burrito shop  
\- Bus route  
\- BUS\_LINE  
\- Business consultant  
\- Business Service  
\- Butcher Shop

### C

\- Cabinet and worktop shop  
\- CAFE  
\- Café  
\- Cajun & creole restaurant  
\- Cake shop  
\- Cambodian restaurant  
\- CAMBODIAN\_RESTAURANT  
\- Campus building  
\- Candle shop  
\- Candy Store  
\- CANDY\_STORE  
\- CANOE\_KAYAK\_RENTAL\_SHOP  
\- CAPITOL\_BUILDING  
\- Car hire  
\- Car wash  
\- CAR\_STEREO\_STORE  
\- CAR\_WASH\_DETAILING  
\- Caravan dealership  
\- Career Counselor  
\- Cargo and freight company  
\- CARGO\_FREIGHT  
\- Caribbean restaurant  
\- Caribbean Restaurant  
\- Carnival supply shop  
\- Carpet and flooring shop  
\- Carpet Cleaner  
\- CARPET\_CLEANER  
\- CASH\_ADVANCE\_SERVICE  
\- Chaat place  
\- Chamber Music Ensemble  
\- Charity organisation  
\- CHEF  
\- Chef  
\- Child development  
\- Child protection service  
\- CHILDRENS\_CLOTHING\_STORE  
\- CHIMNEY\_SWEEPER  
\- Chiropractor  
\- CHOCOLATE\_SHOP  
\- Church  
\- Churros Shop  
\- CIVILIZATION\_MUSEUM  
\- Cleaning Service  
\- CLOTHING\_SUPPLY\_DISTRIBUTION  
\- Cocktail Bar  
\- COLLECTION\_AGENCY  
\- COLLEGE\_UNIVERSITY\_BOOKSTORE  
\- COLUMNIST  
\- Comic Bookstore  
\- COMMERCIAL\_TRUCK\_DEALER  
\- Community Center  
\- Community College  
\- Community museum  
\- Community School  
\- Community school  
\- Community Service  
\- COMMUNITY\_GARDEN  
\- Companies & organisations  
\- COMPANY  
\- Company  
\- Computer Company  
\- Computer Training School  
\- COMPUTER\_STORE  
\- Computers (brand)  
\- Computers (Brand)  
\- Concert tour  
\- Concert Tour Manager  
\- CONSULTING\_COMPANY  
\- Contract lawyer  
\- Contract Lawyer  
\- Convenience store  
\- Convent & Monastery  
\- Convention Center  
\- Cooking School  
\- Corporate lawyer  
\- Cosmetic dentist  
\- Cosmetology school  
\- Costume designer  
\- COUNSELING\_MENTAL\_HEALTH  
\- Country house  
\- Country/region  
\- COUNTY  
\- Courthouse  
\- Coworking space  
\- CRAFTS  
\- Crafts  
\- Credit Counseling Service  
\- Cricket Ground  
\- CRIMINAL\_LAWYER  
\- CRPERIE  
\- Cruise Line  
\- CRYPTO\_ATM  
\- Cultural Center  
\- CULTURAL\_GIFTS\_STORE

### D

\- Dairy Farm  
\- Damage Restoration Service  
\- Dance school  
\- DANCER  
\- Dating service  
\- Dating Service  
\- Day Spa  
\- Defence company  
\- DENTAL\_CLINIC  
\- Dentist & Dental Office  
\- DEPARTMENT\_STORE  
\- Dermatologist  
\- DESIGNER  
\- Dessert Shop  
\- DESSERT\_RESTAURANT  
\- Dietician  
\- DIGITAL\_CREATOR  
\- Dim sum restaurant  
\- Disability service  
\- Dive Bar  
\- DIVE\_BAR  
\- Divorce & Family Lawyer  
\- Dock  
\- Dog Breeder  
\- DOG\_TRAINING  
\- Dominican Restaurant  
\- Donut Shop  
\- Doughnut shop  
\- DRINK  
\- Drinking Fountain  
\- Drive In Restaurant  
\- Driver and Vehicle Standards Agency  
\- Driver improvement course  
\- Driving range  
\- DRIVING\_SCHOOL  
\- DRUGS  
\- DUI\_LAWYER  
\- DUTYFREE\_SHOP

### E

\- Eastern Orthodox Church  
\- Editorial/opinion  
\- Education website  
\- Educational consultant  
\- Educational research centre  
\- Educational supply shop  
\- EDUCATIONAL\_RESEARCH  
\- EDUCATIONAL\_SUPPLIES  
\- Elected official  
\- Electric Vehicle Charging Station  
\- ELECTRIC\_VEHICLE\_CHARGING\_STATION  
\- ELECTRIC\_VEHICLE\_DEALERSHIP  
\- Electricity provider  
\- Electronics  
\- Electronics Store  
\- ELECTRONICS\_STORE  
\- Elementary School  
\- ELEMENTARY\_SCHOOL  
\- Empanada shop  
\- Empanada Shop  
\- EMPLOYMENT\_AGENCY  
\- ENDOCRINOLOGISTS  
\- Endodontist  
\- Energy Company  
\- ENGINEERING\_SERVICE  
\- Escrow Service  
\- Estate agent  
\- Ethiopian Restaurant  
\- European restaurant  
\- Event Videographer  
\- EVENT\_SPACE  
\- Exchange Program  
\- EXCHANGE\_PROGRAM  
\- EXECUTIVE\_FILM\_PRODUCER  
\- Eye care centre

### F

\- FAIRGROUND  
\- Family Style Restaurant  
\- FAMILY\_STYLE\_RESTAURANT  
\- FAN\_PAGE  
\- Farm  
\- Farmstay  
\- Fashion Designer  
\- Fashion designer  
\- Fashion model  
\- Fashion Stylist  
\- FASHION\_ACCESSORIES  
\- FASHION\_COMPANY  
\- FASHION\_STYLE  
\- Fast food restaurant  
\- FENCING\_CLUB  
\- FERTILITY\_CLINIC  
\- FERTILITY\_DOCTOR  
\- Field  
\- FIELD  
\- Film critic  
\- Film music supervisor  
\- Film Music Supervisor  
\- Film producer  
\- Film Production Manager  
\- Film sound designer  
\- Film sound editor  
\- FILM\_PRODUCTION\_MANAGER  
\- Finance Company  
\- Financial service  
\- FINANCIAL\_PLANNING  
\- FIRE\_PROTECTION  
\- FIREWORKS\_RETAILER  
\- First Aid Class  
\- Fish & Chips Restaurant  
\- Fish market  
\- Fish Market  
\- FISHING\_SPOT  
\- FISHING\_STORE  
\- Fitness & workouts  
\- Fitness Model  
\- FITNESS\_WORKOUTS  
\- Fjord/Loch  
\- Flea Market  
\- FLIGHT\_SCHOOL  
\- Florist  
\- FOOD  
\- Food and drink  
\- Food consultant  
\- Food delivery service  
\- Food hall  
\- Food Truck  
\- FOOD\_DELIVERY\_SERVICE  
\- FOOD\_STAND  
\- FOOD\_TRUCK  
\- Forestry & Logging  
\- Forestry Service  
\- FRIENDSHIPS  
\- Friuli Venezia Giulia Restaurant  
\- Funeral service & cemetery  
\- Funicular railway  
\- Furniture repair & upholstery service

### G

\- GAFFER  
\- GAMBLING  
\- Game Publisher  
\- Game publisher  
\- Garage Door Service  
\- GARAGE\_DOOR\_SERVICES  
\- Garden Center  
\- Gas & chemical service  
\- GAS\_STATION  
\- Gastroenterologist  
\- GAY\_BAR  
\- Gelateria  
\- Gelato Shop  
\- GENEALOGIST  
\- GENERAL\_DENTIST  
\- Geologic Service  
\- Geological service  
\- Geriatrician  
\- Glass & mirror shop  
\- GO\_KARTING  
\- Golf Cart Dealership  
\- Golf Course & Country Club  
\- Golf Instructor  
\- GONDOLA\_LIFT  
\- Graphic Designer  
\- GRAPHIC\_DESIGN  
\- Groomer  
\- Gun Store  
\- GUN\_RANGE

### H

\- Hainan restaurant  
\- Hair replacement service  
\- Hair Replacement Service  
\- HAIRPIECES\_EXTENSIONS  
\- Haitian Restaurant  
\- Haitian restaurant  
\- Halal Restaurant  
\- HARBOR  
\- Health & wellness website  
\- Health food restaurant  
\- HEALTH\_FOOD\_STORE  
\- Herb Shop  
\- HERBAL\_MEDICINE\_STORE  
\- HIGH\_SCHOOL  
\- Highway  
\- Himalayan restaurant  
\- Historical tour agency  
\- Hockey Arena  
\- Hockey Field / Rink  
\- HOLIDAYS\_CELEBRATIONS  
\- Home & Garden Store  
\- Home and garden shop  
\- Home Health Care Service  
\- Home Security Company  
\- Home Theater Store  
\- HOME\_SECURITY  
\- HOME\_THEATER\_STORE  
\- HOME\_WINDOW\_SERVICE  
\- Horse riding centre  
\- Horse Riding School  
\- Horseback Riding Center  
\- HORSEBACK\_RIDING\_SERVICE  
\- Hot air balloon tour agency  
\- Hot Air Balloon Tour Agency  
\- Hot spring  
\- HOT\_SPRING  
\- Hotel & Lodging  
\- HOTEL\_BAR  
\- HOUSE\_PAINTER  
\- HOUSE\_SITTER  
\- HOUSEWARES  
\- Housing assistance service  
\- HOUSING\_ASSISTANCE\_SERVICE  
\- Hydro Energy Service

### I

\- IG\_EDITOR  
\- ILLUSTRATOR  
\- Image consultant  
\- IMAGE\_CONSULTANT  
\- Immigration Lawyer  
\- Independent Bookstore  
\- Indian Chinese restaurant  
\- Indian Restaurant  
\- INDIAN\_CHINESE\_RESTAURANT  
\- Indo Chinese Restaurant  
\- Indo-Chinese restaurant  
\- Indoor Golf Course  
\- Information Technology Company  
\- INN  
\- INSURANCE\_AGENT  
\- Intellectual Property Lawyer  
\- Intellectual property solicitor  
\- Interest  
\- INTERGOVERNMENTAL\_ORGANIZATION  
\- INTERIOR\_DESIGNER  
\- Internet café  
\- Internet Marketing Service  
\- INTERNET\_MARKETING\_SERVICE  
\- Inventory control service  
\- Investment management company  
\- INVESTMENT\_MANAGEMENT\_COMPANY  
\- Irish Restaurant  
\- IRISH\_RESTAURANT  
\- Island  
\- Italian restaurant

### J

\- Jamaican restaurant  
\- JANITORIAL\_SERVICE  
\- Javanese restaurant  
\- Jet Ski Rental  
\- Jewelry & Watches Store  
\- Jewelry/watches  
\- Jobs and occupations

### K

\- Kingdom Hall  
\- Kitchen & Bath Contractor  
\- Kitchen/cooking  
\- Kiteboarding Center  
\- Korean Barbecue Restaurant  
\- Kushikatsu restaurant  
\- KUSHIKATSU\_RESTAURANT

### L

\- Labor Union  
\- LABOR\_EMPLOYMENT\_LAW  
\- Landlord & tenant lawyer  
\- LANDLORD\_TENANT\_LAWYER  
\- Landscape Company  
\- Landscape company  
\- Language School  
\- Laser Hair Removal Service  
\- Latin American restaurant  
\- LAUNDROMAT  
\- LAW\_ENFORCEMENT  
\- LAW\_FIRM  
\- LEATHER\_GOODS\_STORE  
\- LEGAL\_SERVICES  
\- LIGHTING\_FIXTURES  
\- Lingerie and underwear shop  
\- LIQUOR\_STORE  
\- Literary editor  
\- LIVERY\_STABLE  
\- LIVESTOCK\_FARM  
\- Lobbyist  
\- LOCAL\_SERVICES  
\- Locksmith  
\- LOCKSMITH  
\- Logging Contractor  
\- Lottery Retailer  
\- LOTTERY\_RETAILER  
\- Lumberyard  
\- LUTHERAN\_CHURCH

### M

\- Machine Shop  
\- Maharashtrian restaurant  
\- Maid & butler  
\- MAKEUP\_ARTIST  
\- Management Service  
\- Manchu restaurant  
\- Manufacturer/Supplier  
\- Marche Restaurant  
\- Marine supply shop  
\- MARINE\_SERVICE\_STATION  
\- Massage school  
\- MASSAGE\_THERAPIST  
\- Maternity clinic  
\- Mattress Manufacturer  
\- Mattress wholesaler  
\- MEDIA  
\- Medical Center  
\- Medical Clinic  
\- Medical Company  
\- Medical lawyer  
\- Medical Supply Store  
\- MEDICAL\_SCHOOL  
\- MEDICAL\_SERVICE  
\- Meditation Center  
\- Mediterranean Restaurant  
\- MEDITERRANEAN\_RESTAURANT  
\- Men's clothes shop  
\- Men's clothing store  
\- MENS\_CLOTHING\_STORE  
\- MERCHANDISING\_SERVICE  
\- Metal Fabricator  
\- MEXICAN\_RESTAURANT  
\- Middle Eastern restaurant  
\- Middle Eastern Restaurant  
\- Middle School  
\- MIDDLE\_EASTERN\_RESTAURANT  
\- MILITARY\_BASE  
\- Miniature Golf Course  
\- MINIATURE\_GOLF  
\- Mining company  
\- MISSION  
\- Modeling Agency  
\- Modern Art Museum  
\- MODERN\_EUROPEAN\_RESTAURANT  
\- Monarch  
\- MORTGAGE\_BROKERS  
\- MOTEL  
\- Motel  
\- Motorcycle manufacturer  
\- MOTORSPORTS\_STORE  
\- Mountain  
\- MOVER  
\- MOVIE\_TELEVISION\_STUDIO  
\- MOVIE\_WRITER  
\- Moving & Storage Service  
\- Music  
\- Music Award  
\- Music critic  
\- Music Director  
\- Music production studio  
\- Music recording engineer  
\- MUSIC\_COMPOSER  
\- MUSIC\_DIRECTOR  
\- MUSIC\_PRODUCTION  
\- Musical instrument repair shop  
\- MUSICAL\_INSTRUMENT\_REPAIR\_SHOP

### N

\- Nabe restaurant  
\- NABE\_RESTAURANT  
\- Nail Salon  
\- NAIL\_SALON  
\- Nanny  
\- NATIONAL\_PARK  
\- Nature reserve  
\- NCES\_COLLEGE\_GENERATED  
\- Neapolitan Restaurant  
\- Neighbourhood  
\- NEW\_VEHICLES  
\- News & media website  
\- News personality  
\- Newspaper  
\- Nigerian restaurant  
\- Night market  
\- NIGHT\_CLUB  
\- Non-Governmental Organization (NGO)  
\- Nonprofit organization  
\- Novelist  
\- Nursing agency  
\- Nursing School

### O

\- Occupational therapist  
\- Occupational Therapist  
\- OCCUPATIONAL\_SAFETY  
\- OCCUPATIONAL\_THERAPIST  
\- OFFICE\_EQUIPMENT\_STORE  
\- ONCOLOGIST  
\- Oncologist  
\- Online Gambling  
\- Online gambling  
\- Organic food shop  
\- Orthodontist  
\- ORTHOPEDIC\_SHOE\_STORE  
\- OTHER  
\- Other  
\- Outdoor & Sporting Goods Company  
\- OUTDOOR\_PLACES

### P

\- Padangnese Restaurant  
\- Paediatric dentist  
\- Paint shop  
\- Paint Store  
\- PAINTER  
\- Pakistani restaurant  
\- PAKISTANI\_RESTAURANT  
\- Panamanian restaurant  
\- Parsi restaurant  
\- Party and entertainment service  
\- PARTY\_CENTER  
\- PARTY\_SUPPLIES  
\- PASSPORT\_VISA\_SERVICE  
\- PATIO\_GARDEN  
\- Patio/Garden  
\- PATROL\_SECURITY  
\- Paving & asphalt service  
\- Pawn shop  
\- People  
\- Performance & Event Venue  
\- Performance Art Theatre  
\- PERFORMANCE\_ART  
\- Performing arts school  
\- Performing Arts School  
\- PERFORMING\_ARTS  
\- PERFUMERY  
\- Perfumery  
\- Personal blog  
\- Personal Chef  
\- Pet Breeder  
\- Pet Cemetery  
\- Pet Groomer  
\- Pet groomer  
\- Pet Sitter  
\- Pet Supplies  
\- PET\_BREEDER  
\- Petroleum Service  
\- Petting zoo  
\- Pho Restaurant  
\- Photography Studio  
\- Physical gambling  
\- Physical Therapist  
\- PHYSICAL\_GAMBLING  
\- Picnic Ground  
\- PICTURE\_FRAME\_STORE  
\- Pier  
\- Pilates Studio  
\- PILATES\_STUDIO  
\- Plastic surgeon  
\- Plastic Surgeon  
\- PLUMBER  
\- Plumbing Service  
\- Podcast  
\- POLITICAL\_IDEOLOGY  
\- Pool & Billiard Hall  
\- Popcorn Shop  
\- POPUP\_SHOP  
\- PORT  
\- Portable toilet hire  
\- PORTABLE\_BUILDING\_SERVICE  
\- PORTABLE\_TOILET\_RENTALS  
\- Post Office  
\- POST\_OFFICE  
\- Pregnancy Care Center  
\- Pregnancy care centre  
\- Preschool  
\- Printing Service  
\- PRINTING\_SERVICE  
\- Prison & Correctional Facility  
\- Private Investigator  
\- Private Members Club  
\- Production Coordinator  
\- PRODUCTION\_COORDINATOR  
\- Professional Association  
\- Professional Service  
\- Professional Sports League  
\- Professional Sports Team  
\- PROFESSIONAL\_SPORT\_TEAM  
\- Property investment company  
\- PROPERTY\_MANAGEMENT  
\- Prosthodontist  
\- PUB  
\- Public Market  
\- Public market  
\- Public service  
\- Public Service  
\- Public Swimming Pool  
\- PUBLIC\_SERVICES  
\- PUBLIC\_SQUARE  
\- Puerto Rican restaurant  
\- PUERTO\_RICAN\_RESTAURANT  
\- Puglia restaurant  
\- Punjabi restaurant

### Q

\- Quay

### R

\- RACE\_TRACK  
\- Racquetball court  
\- Radio station  
\- Radiologist  
\- RADIOLOGISTS  
\- RAILROAD  
\- Ramen restaurant  
\- Rapper  
\- REAL\_ESTATE\_AGENT  
\- REAL\_ESTATE\_INVESTMENT  
\- REAL\_ESTATE\_SERVICE  
\- Record label  
\- Recreation & sports website  
\- Recreation and sport website  
\- Recreation centre  
\- Recreation Spot  
\- RECREATION\_CENTER  
\- RECREATION\_SPOT  
\- RECRUITER  
\- Recycling centre  
\- Reference website  
\- Reference Website  
\- Reflexologist  
\- Religion & spirituality  
\- Religious centre  
\- Religious goods shop  
\- Religious Goods Store  
\- Religious School  
\- RELIGIOUS\_GOODS\_STORE  
\- Rental Shop  
\- Reproductive service  
\- REPRODUCTIVE\_SERVICES  
\- Reptile Pet Store  
\- RESTAURANT\_WHOLESALE  
\- RETAIL\_BANK  
\- Retirement and assisted living facility  
\- RETIREMENT\_ASSISTED\_LIVING\_FACILITY  
\- Rheumatologist  
\- RHEUMATOLOGISTS  
\- Robotics Company  
\- Rock Climbing Gym  
\- Rodeo  
\- ROLLER\_SKATING\_RINK  
\- Roller-skating rink  
\- Roman Restaurant  
\- Rose garden  
\- ROSE\_GARDEN  
\- Rugby field  
\- Rugby stadium  
\- Russian restaurant  
\- RUSSIAN\_RESTAURANT  
\- RV Rental

### S

\- Safety & First Aid Service  
\- Sake Bar  
\- SAKE\_BAR  
\- Salvadoran Restaurant  
\- Sandwich shop  
\- Satire/Parody  
\- SCHOOL\_TEAM  
\- Science, technology and engineering  
\- SCIENTIST  
\- Scooter Rental  
\- Scottish Restaurant  
\- Screen Printing & Embroidery  
\- Scuba Diving Center  
\- Scuba diving instructor  
\- SCUBA\_INSTRUCTOR  
\- Sculpture garden  
\- SEAFOOD\_RESTAURANT  
\- Seaplane base  
\- Seasonal shop  
\- Secondary school  
\- Security Guard Service  
\- SELF\_DEFENSE\_SCHOOL  
\- SELFSTORAGE\_FACILITY  
\- Senegalese restaurant  
\- SEPTIC\_TANK\_SERVICE  
\- Service station  
\- Set Decorator  
\- SET\_DESIGNER  
\- Sewer Service  
\- SEWING\_SEAMSTRESS  
\- Sex Therapist  
\- Shaved ice shop  
\- SHAVED\_ICE\_SHOP  
\- Shipping Supply & Service  
\- SHIPPING\_SUPPLY\_SERVICE  
\- Shoe repair shop  
\- SHOE\_STORE  
\- Shooting/Hunting Range  
\- Shopping District  
\- Shopping district  
\- Shopping Mall  
\- Shopping service  
\- SHOPPING\_SERVICE  
\- Show  
\- Shredding Service  
\- Singaporean restaurant  
\- SINGAPOREAN\_RESTAURANT  
\- SINGER  
\- Skate Shop  
\- Ski & snowboard shop  
\- Ski Resort  
\- SKI\_SNOWBOARD\_SHOP  
\- Skin Care Service  
\- Skincare service  
\- Skydiving centre  
\- Smog Emissions Check Station  
\- SNORKELING\_SPOT  
\- SOBA\_RESTAURANT  
\- Social club  
\- Social media company  
\- SOCIAL\_CLUB  
\- SOCIAL\_SERVICES  
\- Society & culture website  
\- Software  
\- Software company  
\- Solar Energy Company  
\- Solar energy company  
\- SOLAR\_ENERGY\_COMPANY  
\- Soprano singer  
\- Sorority & fraternity  
\- SORORITY\_FRATERNITY  
\- Soul Food Restaurant  
\- South Indian Restaurant  
\- SOUTH\_INDIAN\_RESTAURANT  
\- SOUTHWESTERN\_RESTAURANT  
\- SOUVENIR\_SHOP  
\- SPA  
\- Spanish Restaurant  
\- SPANISH\_RESTAURANT  
\- Special effects director  
\- Specialist school  
\- SPEECH\_PATHOLOGIST  
\- SPEECH\_THERAPIST  
\- Speechwriter  
\- SPIRITUAL\_LEADER  
\- Sport and recreation  
\- Sport Psychologist  
\- Sports & recreation venue  
\- Sports bar  
\- Sports team  
\- SPORTS\_AND\_RECREATION  
\- SPORTS\_TEAM  
\- Squash Court  
\- SRI\_LANKAN\_RESTAURANT  
\- Stadium, Arena & Sports Venue  
\- Stadium, arena and sports venue  
\- Stationary store  
\- Statue & fountain  
\- STD\_TESTING\_CENTER  
\- Steakhouse  
\- Street  
\- Street art  
\- Student Union  
\- Students' union  
\- Subway Station  
\- Sugaring Service  
\- Supermarket  
\- Surgeon  
\- Surgical centre  
\- Sushi restaurant  
\- SWABIAN\_RESTAURANT  
\- Sweet shop  
\- Swimming Instructor  
\- Swimming Pool & Hot Tub Service  
\- Swimming Pool Cleaner

### T

\- Taco Restaurant  
\- Taco restaurant  
\- Tai Chi Studio  
\- Tailor  
\- Taiwanese Restaurant  
\- Talent manager  
\- Talent Manager  
\- Tanning salon  
\- TANNING\_SALON  
\- TANNING\_SALON\_SUPPLIER  
\- Tapas bar & restaurant  
\- Tatar Restaurant  
\- Tattoo & Piercing Shop  
\- TATTOO\_REMOVAL\_SERVICE  
\- Tax preparation service  
\- Taxidermist  
\- Teacher  
\- TEACHER  
\- Teen & children's website  
\- Teeth whitening service  
\- TEETH\_WHITENING  
\- Telemarketing service  
\- Television repair service  
\- TELEVISION\_SERVICE\_PROVIDER  
\- Tempura Restaurant  
\- TENNIS\_STADIUM  
\- Tenor Singer  
\- TEPPANYAKI\_RESTAURANT  
\- Test Preparation Center  
\- TEXMEX\_RESTAURANT  
\- Textile company  
\- TEXTILES  
\- Thai Restaurant  
\- THAI\_RESTAURANT  
\- Theatrical play  
\- Theatrical Play  
\- THEATRICAL\_PRODUCTIONS  
\- Theme restaurant  
\- Therapist  
\- Thrift & Consignment Store  
\- Tiki Bar  
\- TIKI\_BAR  
\- Tobacco shop  
\- Tobacco Store  
\- TOPIC\_APPLIANCES  
\- TOPIC\_ARTS\_ENTERTAINMENT  
\- TOPIC\_AUTOMOTIVE  
\- TOPIC\_BOOK\_STORE  
\- TOPIC\_BUSINESS\_SERVICES  
\- TOPIC\_FOOD\_GROCERY  
\- TOPIC\_HOTEL  
\- TOPIC\_JUST\_FOR\_FUN  
\- TOPIC\_MOUNTAIN  
\- TOPIC\_NEWSPAPER  
\- TOPIC\_OFFICE\_SUPPLIES  
\- Tourist Attraction  
\- TOWNSHIP  
\- Toy manufacturer  
\- Toy shop  
\- TOY\_STORE  
\- Trade Association  
\- Trade association  
\- Trade School  
\- TRADE\_SCHOOL  
\- TRAIN\_STATION  
\- TRANSIT\_SYSTEM  
\- TRANSLATOR  
\- Transport system  
\- Travel agency  
\- Travel Service  
\- Travel service  
\- TREE\_CUTTING\_SERVICE  
\- Truck Rental  
\- TRUCK\_REPAIR\_SHOP  
\- Tunisian restaurant  
\- TURKISH\_RESTAURANT  
\- TV  
\- TV Season  
\- TV\_GENRE  
\- TV\_MOVIE\_AWARD  
\- TV/Movie Award

### U

\- Ugandan restaurant  
\- Ukrainian Restaurant  
\- University  
\- Used vehicles

### V

\- Van repair shop  
\- Vehicle consultant  
\- Vehicle detailing service  
\- Vehicle parts shop  
\- Vehicle restoration service  
\- Vehicle, aircraft and boat  
\- Vending machine sales and service  
\- Venezuelan restaurant  
\- Video game  
\- Video game producer  
\- Video Game Programmer  
\- Video Game Store  
\- VIDEO\_GAME\_PROGRAMMER  
\- VIDEO\_GAME\_STORE  
\- VIDEOGRAPHER  
\- VINTAGE\_STORE  
\- Vinyl Siding Company  
\- VISUAL\_EFFECTS\_ARTIST  
\- Vitamin supplement shop  
\- VITAMIN\_SUPPLEMENTS  
\- Volleyball Court

### W

\- Wagashi restaurant  
\- Waste Management Company  
\- Waste management company  
\- Waxing Service  
\- WEB\_DESIGN  
\- Wedding Planning Service  
\- Wedding Venue  
\- Well Water Drilling Service  
\- Wholesale & Supply Store  
\- WHOLESALE\_BAKERY  
\- WINE\_BAR  
\- WINE\_SPIRITS  
\- Winery/Vineyard  
\- Women's health clinic  
\- WOMENS\_CLOTHING\_STORE  
\- WRITING\_SERVICE

### X

\- Xinjiang Restaurant

### Y

\- Yakitori restaurant  
\- Yoshoku restaurant  
\- Youth organisation