Search creators

curl --request POST \
  --url https://api.unif.dev/v1/creators/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "market": "US",
  "period": {
    "preset": "last_30d"
  },
  "currency": "USD",
  "filters": {
    "category_ids": [
      "cat_beauty_personal_care"
    ],
    "followers": {
      "gte": 20000,
      "lte": 300000
    },
    "revenue": {
      "gte": 25000
    },
    "gpm": {
      "gte": 40
    }
  },
  "sort": [
    {
      "field": "gpm",
      "direction": "desc"
    }
  ],
  "limit": 50
}
'

import requests

url = "https://api.unif.dev/v1/creators/search"

payload = {
    "market": "US",
    "period": { "preset": "last_30d" },
    "currency": "USD",
    "filters": {
        "category_ids": ["cat_beauty_personal_care"],
        "followers": {
            "gte": 20000,
            "lte": 300000
        },
        "revenue": { "gte": 25000 },
        "gpm": { "gte": 40 }
    },
    "sort": [
        {
            "field": "gpm",
            "direction": "desc"
        }
    ],
    "limit": 50
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    market: 'US',
    period: {preset: 'last_30d'},
    currency: 'USD',
    filters: {
      category_ids: ['cat_beauty_personal_care'],
      followers: {gte: 20000, lte: 300000},
      revenue: {gte: 25000},
      gpm: {gte: 40}
    },
    sort: [{field: 'gpm', direction: 'desc'}],
    limit: 50
  })
};

fetch('https://api.unif.dev/v1/creators/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unif.dev/v1/creators/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'market' => 'US',
    'period' => [
        'preset' => 'last_30d'
    ],
    'currency' => 'USD',
    'filters' => [
        'category_ids' => [
                'cat_beauty_personal_care'
        ],
        'followers' => [
                'gte' => 20000,
                'lte' => 300000
        ],
        'revenue' => [
                'gte' => 25000
        ],
        'gpm' => [
                'gte' => 40
        ]
    ],
    'sort' => [
        [
                'field' => 'gpm',
                'direction' => 'desc'
        ]
    ],
    'limit' => 50
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unif.dev/v1/creators/search"

	payload := strings.NewReader("{\n  \"market\": \"US\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"currency\": \"USD\",\n  \"filters\": {\n    \"category_ids\": [\n      \"cat_beauty_personal_care\"\n    ],\n    \"followers\": {\n      \"gte\": 20000,\n      \"lte\": 300000\n    },\n    \"revenue\": {\n      \"gte\": 25000\n    },\n    \"gpm\": {\n      \"gte\": 40\n    }\n  },\n  \"sort\": [\n    {\n      \"field\": \"gpm\",\n      \"direction\": \"desc\"\n    }\n  ],\n  \"limit\": 50\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unif.dev/v1/creators/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"market\": \"US\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"currency\": \"USD\",\n  \"filters\": {\n    \"category_ids\": [\n      \"cat_beauty_personal_care\"\n    ],\n    \"followers\": {\n      \"gte\": 20000,\n      \"lte\": 300000\n    },\n    \"revenue\": {\n      \"gte\": 25000\n    },\n    \"gpm\": {\n      \"gte\": 40\n    }\n  },\n  \"sort\": [\n    {\n      \"field\": \"gpm\",\n      \"direction\": \"desc\"\n    }\n  ],\n  \"limit\": 50\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unif.dev/v1/creators/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"market\": \"US\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"currency\": \"USD\",\n  \"filters\": {\n    \"category_ids\": [\n      \"cat_beauty_personal_care\"\n    ],\n    \"followers\": {\n      \"gte\": 20000,\n      \"lte\": 300000\n    },\n    \"revenue\": {\n      \"gte\": 25000\n    },\n    \"gpm\": {\n      \"gte\": 40\n    }\n  },\n  \"sort\": [\n    {\n      \"field\": \"gpm\",\n      \"direction\": \"desc\"\n    }\n  ],\n  \"limit\": 50\n}"

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "crt_01k3m9x7v2q8r4t6y0b1n5d7fa",
      "object": "creator",
      "channel": "tiktok_shop",
      "market": "US",
      "name": "June",
      "handle": "@glowbyjune",
      "url": "<string>",
      "avatar_url": "<string>",
      "bio": "<string>",
      "followers": 123,
      "categories": [
        {
          "id": "cat_beauty_personal_care",
          "name": "Beauty & Personal Care",
          "path": [
            "<string>"
          ]
        }
      ],
      "agency": "<string>",
      "metrics": {
        "revenue": 123,
        "units_sold": 123,
        "gpm": 123,
        "avg_commission_rate": 123,
        "products_count": 123,
        "shops_count": 123,
        "videos_count": 123,
        "livestreams_count": 123,
        "avg_views_per_video": 123,
        "engagement_rate": 123,
        "follower_growth": 123
      },
      "period": {
        "start": "2023-12-25",
        "end": "2023-12-25",
        "granularity": "day",
        "adjusted": true
      },
      "currency": "<string>",
      "meta": {
        "refreshed_at": "2023-11-07T05:31:56Z",
        "completeness": 0.5,
        "missing_fields": [
          "<string>"
        ]
      }
    }
  ],
  "next_cursor": "<string>",
  "total_count": 123,
  "period": {
    "start": "2023-12-25",
    "end": "2023-12-25",
    "granularity": "day",
    "adjusted": true
  },
  "currency": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "filters.revenue.gte must be a non-negative number.",
    "param": "filters.revenue.gte",
    "doc_url": "https://unif.dev/docs/platform/errors#parameter_invalid",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This request costs 25 credits and 4 remain in the current period.",
    "doc_url": "https://unif.dev/docs/platform/credits",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

POST

https://api.unif.dev/v1

creators

Search creators

curl --request POST \
  --url https://api.unif.dev/v1/creators/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "market": "US",
  "period": {
    "preset": "last_30d"
  },
  "currency": "USD",
  "filters": {
    "category_ids": [
      "cat_beauty_personal_care"
    ],
    "followers": {
      "gte": 20000,
      "lte": 300000
    },
    "revenue": {
      "gte": 25000
    },
    "gpm": {
      "gte": 40
    }
  },
  "sort": [
    {
      "field": "gpm",
      "direction": "desc"
    }
  ],
  "limit": 50
}
'

import requests

url = "https://api.unif.dev/v1/creators/search"

payload = {
    "market": "US",
    "period": { "preset": "last_30d" },
    "currency": "USD",
    "filters": {
        "category_ids": ["cat_beauty_personal_care"],
        "followers": {
            "gte": 20000,
            "lte": 300000
        },
        "revenue": { "gte": 25000 },
        "gpm": { "gte": 40 }
    },
    "sort": [
        {
            "field": "gpm",
            "direction": "desc"
        }
    ],
    "limit": 50
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    market: 'US',
    period: {preset: 'last_30d'},
    currency: 'USD',
    filters: {
      category_ids: ['cat_beauty_personal_care'],
      followers: {gte: 20000, lte: 300000},
      revenue: {gte: 25000},
      gpm: {gte: 40}
    },
    sort: [{field: 'gpm', direction: 'desc'}],
    limit: 50
  })
};

fetch('https://api.unif.dev/v1/creators/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unif.dev/v1/creators/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'market' => 'US',
    'period' => [
        'preset' => 'last_30d'
    ],
    'currency' => 'USD',
    'filters' => [
        'category_ids' => [
                'cat_beauty_personal_care'
        ],
        'followers' => [
                'gte' => 20000,
                'lte' => 300000
        ],
        'revenue' => [
                'gte' => 25000
        ],
        'gpm' => [
                'gte' => 40
        ]
    ],
    'sort' => [
        [
                'field' => 'gpm',
                'direction' => 'desc'
        ]
    ],
    'limit' => 50
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unif.dev/v1/creators/search"

	payload := strings.NewReader("{\n  \"market\": \"US\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"currency\": \"USD\",\n  \"filters\": {\n    \"category_ids\": [\n      \"cat_beauty_personal_care\"\n    ],\n    \"followers\": {\n      \"gte\": 20000,\n      \"lte\": 300000\n    },\n    \"revenue\": {\n      \"gte\": 25000\n    },\n    \"gpm\": {\n      \"gte\": 40\n    }\n  },\n  \"sort\": [\n    {\n      \"field\": \"gpm\",\n      \"direction\": \"desc\"\n    }\n  ],\n  \"limit\": 50\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unif.dev/v1/creators/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"market\": \"US\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"currency\": \"USD\",\n  \"filters\": {\n    \"category_ids\": [\n      \"cat_beauty_personal_care\"\n    ],\n    \"followers\": {\n      \"gte\": 20000,\n      \"lte\": 300000\n    },\n    \"revenue\": {\n      \"gte\": 25000\n    },\n    \"gpm\": {\n      \"gte\": 40\n    }\n  },\n  \"sort\": [\n    {\n      \"field\": \"gpm\",\n      \"direction\": \"desc\"\n    }\n  ],\n  \"limit\": 50\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unif.dev/v1/creators/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"market\": \"US\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"currency\": \"USD\",\n  \"filters\": {\n    \"category_ids\": [\n      \"cat_beauty_personal_care\"\n    ],\n    \"followers\": {\n      \"gte\": 20000,\n      \"lte\": 300000\n    },\n    \"revenue\": {\n      \"gte\": 25000\n    },\n    \"gpm\": {\n      \"gte\": 40\n    }\n  },\n  \"sort\": [\n    {\n      \"field\": \"gpm\",\n      \"direction\": \"desc\"\n    }\n  ],\n  \"limit\": 50\n}"

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "id": "crt_01k3m9x7v2q8r4t6y0b1n5d7fa",
      "object": "creator",
      "channel": "tiktok_shop",
      "market": "US",
      "name": "June",
      "handle": "@glowbyjune",
      "url": "<string>",
      "avatar_url": "<string>",
      "bio": "<string>",
      "followers": 123,
      "categories": [
        {
          "id": "cat_beauty_personal_care",
          "name": "Beauty & Personal Care",
          "path": [
            "<string>"
          ]
        }
      ],
      "agency": "<string>",
      "metrics": {
        "revenue": 123,
        "units_sold": 123,
        "gpm": 123,
        "avg_commission_rate": 123,
        "products_count": 123,
        "shops_count": 123,
        "videos_count": 123,
        "livestreams_count": 123,
        "avg_views_per_video": 123,
        "engagement_rate": 123,
        "follower_growth": 123
      },
      "period": {
        "start": "2023-12-25",
        "end": "2023-12-25",
        "granularity": "day",
        "adjusted": true
      },
      "currency": "<string>",
      "meta": {
        "refreshed_at": "2023-11-07T05:31:56Z",
        "completeness": 0.5,
        "missing_fields": [
          "<string>"
        ]
      }
    }
  ],
  "next_cursor": "<string>",
  "total_count": 123,
  "period": {
    "start": "2023-12-25",
    "end": "2023-12-25",
    "granularity": "day",
    "adjusted": true
  },
  "currency": "<string>"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "filters.revenue.gte must be a non-negative number.",
    "param": "filters.revenue.gte",
    "doc_url": "https://unif.dev/docs/platform/errors#parameter_invalid",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This request costs 25 credits and 4 remain in the current period.",
    "doc_url": "https://unif.dev/docs/platform/credits",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Send your workspace API key as a bearer token:

Authorization: Bearer unif_sk_live_...

Keys are scoped to a single workspace. See Authentication.

Body

application/json

channel

enum<string>

A sales channel — the commerce surface a request is about. Behind each channel is a cascade of data sources, tried in cost order until one verifies; the roster is published, but which source answered a given row is not carried in the response, so the cascade can be re-tuned without breaking your code.

Available options:

tiktok_shop

Example:

"tiktok_shop"

market

enum<string>

An ISO 3166-1 alpha-2 country code identifying a channel storefront.

Available options:

US,

GB,

IE,

ES,

FR,

DE,

IT,

ID,

TH,

VN,

MY,

PH,

SG,

JP,

BR,

MX

Example:

"US"

period

object

The window a metric is measured over. Supply either preset, or both start and end. Periods are whole days in the market's local time zone.

Hide child attributes

period.preset

enum<string>

default:last_30d

Available options:

last_7d,

last_30d,

last_90d,

last_180d,

month_to_date,

previous_month

period.start

string<date>

First day

period.end

string<date>

Last day

Examples:

{ "preset": "last_30d" }

{
  "start": "2026-08-01",
  "end": "2026-08-31"
}

currency

string

default:USD

ISO 4217 code. Every monetary field in the response is converted to it.

sort

object[]

Maximum array length: 3

Hide child attributes

sort.field

string

required

A metric or attribute name. Sortable fields are listed on each entity in the metrics reference.

sort.direction

enum<string>

default:desc

Available options:

asc,

desc

limit

integer

default:25

Required range: 1 <= x <= 100

cursor

string

The next_cursor from a previous response.

filters

object

Hide child attributes

filters.keywords

string

Matches creator name

filters.creator_ids

string[]

filters.category_ids

string[]

filters.followers

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.followers.gte

number

filters.followers.gt

number

filters.followers.lte

number

filters.followers.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.revenue

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.revenue.gte

number

filters.revenue.gt

number

filters.revenue.lte

number

filters.revenue.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.units_sold

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.units_sold.gte

number

filters.units_sold.gt

number

filters.units_sold.lte

number

filters.units_sold.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.gpm

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.gpm.gte

number

filters.gpm.gt

number

filters.gpm.lte

number

filters.gpm.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.engagement_rate

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.engagement_rate.gte

number

filters.engagement_rate.gt

number

filters.engagement_rate.lte

number

filters.engagement_rate.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.avg_views_per_video

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.avg_views_per_video.gte

number

filters.avg_views_per_video.gt

number

filters.avg_views_per_video.lte

number

filters.avg_views_per_video.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.avg_commission_rate

object

An inclusive or exclusive numeric bound. Combine keys to express a closed range.

Hide child attributes

filters.avg_commission_rate.gte

number

filters.avg_commission_rate.gt

number

filters.avg_commission_rate.lte

number

filters.avg_commission_rate.lt

number

Example:

{ "gte": 15, "lte": 45 }

filters.has_livestreams

boolean

Response

Matching creators.

object

string

required

Allowed value: "list"

has_more

boolean

required

Whether another page exists.

data

object[]

required

Hide child attributes

data.id

string

Example:

"crt_01k3m9x7v2q8r4t6y0b1n5d7fa"

data.object

string

Allowed value: "creator"

data.channel

enum<string>

Available options:

tiktok_shop

Example:

"tiktok_shop"

data.market

enum<string>

An ISO 3166-1 alpha-2 country code identifying a channel storefront.

Available options:

US,

GB,

IE,

ES,

FR,

DE,

IT,

ID,

TH,

VN,

MY,

PH,

SG,

JP,

BR,

MX

Example:

"US"

data.name

string

Example:

"June"

data.handle

string

Example:

"@glowbyjune"

data.url

string<uri>

data.avatar_url

string<uri>

data.bio

string | null

data.followers

integer | null

data.categories

object[]

Categories the creator actually sells in, ranked by revenue share.

Hide child attributes

data.categories.id

string

Example:

"cat_beauty_personal_care"

data.categories.name

string

Example:

"Beauty & Personal Care"

data.categories.path

string[]

Names from the root down to this category.

data.agency

string | null

Talent network or MCN, where the channel discloses one.

data.metrics

object

Hide child attributes

data.metrics.revenue

number

Revenue attributed to the creator's content.

data.metrics.units_sold

integer

data.metrics.gpm

number

Gross revenue per thousand views.

data.metrics.avg_commission_rate

number

data.metrics.products_count

integer

Distinct products the creator sold.

data.metrics.shops_count

integer

data.metrics.videos_count

integer

data.metrics.livestreams_count

integer

data.metrics.avg_views_per_video

number

data.metrics.engagement_rate

number

Likes

data.metrics.follower_growth

integer

Net followers gained over the period.

data.period

object

The concrete window a request was measured over, after any preset was expanded and any channel-specific snapping was applied. Always read this rather than assuming you got back exactly the dates you asked for.

Hide child attributes

data.period.start

string<date>

required

data.period.end

string<date>

required

data.period.granularity

enum<string>

The smallest bucket the channel reports for this market.

Available options:

day,

week,

month

data.period.adjusted

boolean

True when the requested dates were snapped to the nearest boundary the channel supports. See Periods and currency.

data.currency

string

data.meta

object

How current and how complete this record is.

Hide child attributes

data.meta.refreshed_at

string<date-time>

When Unif last refreshed this record.

data.meta.completeness

number

Share of the requested fields that were populated.

Required range: 0 <= x <= 1

data.meta.missing_fields

string[]

Fields that are not covered for this channel and market.

next_cursor

string | null

Pass to cursor to fetch the next page. Null on the last page.

total_count

integer | null

Approximate number of matches. Null when the result set is too large to count exactly.

period

object

Hide child attributes

period.start

string<date>

required

period.end

string<date>

required

period.granularity

enum<string>

The smallest bucket the channel reports for this market.

Available options:

day,

week,

month

period.adjusted

boolean

True when the requested dates were snapped to the nearest boundary the channel supports. See Periods and currency.

currency

string

Overview

Meta

Shops

Products

Creators

Videos

Livestreams

Categories

Resolution

Jobs

Lists

Trackers

Webhooks

Usage

Search creators

Authorizations

Body

Response