> ## Documentation Index > Fetch the complete documentation index at: https://unif.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search creators > Find creators by the categories they actually sell in, the revenue they generate and the audience they reach. Filters describe selling behavior, not just follower counts. ## OpenAPI ````yaml /api-reference/openapi.yaml post /creators/search openapi: 3.1.0 info: title: Unif API version: '2026-09-01' summary: One schema for commerce data across every channel. description: > The Unif API returns normalized commerce data — shops, products, creators, videos, livestreams and categories — through a single schema that does not change when the underlying data source does. Each request runs a cascade across the sources behind a channel, in cost order, stopping at the first result that verifies. You are charged for the hit, not for the attempts. See [the waterfall](/docs/concepts/waterfall). Every response is denominated in the currency you ask for, scoped to a market, and measured over a period you control, whichever source answered. **Base URL** ``` https://api.unif.dev/v1 ``` All requests require a bearer token. See [Authentication](/docs/authentication). **Conventions** - Success and failure are carried by the HTTP status code. There is no envelope to unwrap: a `200` body is the object itself, and any `4xx` or `5xx` body is an [error object](/docs/platform/errors). - Lists are cursor-paginated. Read `next_cursor` and stop when `has_more` is false. - Every response carries `X-Request-Id`. Billable responses also carry `X-Unif-Credits-Charged` and `X-Unif-Credits-Remaining`. - Monetary fields are converted to the `currency` you request, and every object repeats the `currency` and `period` it was measured under. contact: name: Unif Support email: support@unif.dev url: https://unif.dev/docs license: name: Proprietary url: https://unif.dev/legal/terms servers: - url: https://api.unif.dev/v1 description: Production security: - bearerAuth: [] tags: - name: Meta description: Workspace, channel availability and field coverage. - name: Shops description: Storefronts and sellers. - name: Products description: Listings, pricing and sales performance. - name: Creators description: Affiliates and influencers who sell. - name: Videos description: Short-form video attributed to sales. - name: Livestreams description: Live selling sessions. - name: Categories description: The normalized category tree and category-level market data. - name: Resolution description: Turn a URL, handle or external ID into a Unif entity. - name: Jobs description: Asynchronous work for large searches, enrichments and exports. - name: Lists description: Saved sets of entities. - name: Trackers description: Scheduled re-checks that emit webhook events on change. - name: Webhooks description: Endpoint registration and delivery settings. - name: Usage description: Credit balance and per-request consumption. paths: /creators/search: post: tags: - Creators summary: Search creators description: > Find creators by the categories they actually sell in, the revenue they generate and the audience they reach. Filters describe selling behavior, not just follower counts. operationId: searchCreators requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatorSearchRequest' examples: midTierBeautyCreators: summary: Mid-tier beauty creators who convert value: 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 responses: '200': description: Matching creators. content: application/json: schema: $ref: '#/components/schemas/CreatorList' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/InsufficientCredits' '429': $ref: '#/components/responses/RateLimited' components: schemas: CreatorSearchRequest: allOf: - $ref: '#/components/schemas/SearchRequestBase' - type: object properties: filters: $ref: '#/components/schemas/CreatorFilters' CreatorList: allOf: - $ref: '#/components/schemas/ListEnvelope' - type: object properties: data: type: array items: $ref: '#/components/schemas/Creator' SearchRequestBase: type: object properties: channel: $ref: '#/components/schemas/Channel' market: $ref: '#/components/schemas/Market' period: $ref: '#/components/schemas/Period' currency: type: string default: USD description: >- ISO 4217 code. Every monetary field in the response is converted to it. sort: type: array maxItems: 3 items: $ref: '#/components/schemas/SortSpec' limit: type: integer minimum: 1 maximum: 100 default: 25 cursor: type: string description: The `next_cursor` from a previous response. CreatorFilters: type: object properties: keywords: type: string description: Matches creator name handle and bio.: null creator_ids: type: array items: type: string category_ids: type: array items: type: string followers: $ref: '#/components/schemas/NumberRange' revenue: $ref: '#/components/schemas/NumberRange' units_sold: $ref: '#/components/schemas/NumberRange' gpm: $ref: '#/components/schemas/NumberRange' engagement_rate: $ref: '#/components/schemas/NumberRange' avg_views_per_video: $ref: '#/components/schemas/NumberRange' avg_commission_rate: $ref: '#/components/schemas/NumberRange' has_livestreams: type: boolean ListEnvelope: type: object required: - object - data - has_more properties: object: type: string const: list has_more: type: boolean description: Whether another page exists. next_cursor: type: - string - 'null' description: Pass to `cursor` to fetch the next page. Null on the last page. total_count: type: - integer - 'null' description: >- Approximate number of matches. Null when the result set is too large to count exactly. period: $ref: '#/components/schemas/ResolvedPeriod' currency: type: string Creator: type: object description: A person who drives attributed sales on a channel. properties: id: type: string examples: - crt_01k3m9x7v2q8r4t6y0b1n5d7fa object: type: string const: creator channel: $ref: '#/components/schemas/Channel' market: $ref: '#/components/schemas/Market' name: type: string examples: - June handle: type: string examples: - '@glowbyjune' url: type: string format: uri avatar_url: type: string format: uri bio: type: - string - 'null' followers: type: - integer - 'null' categories: type: array items: $ref: '#/components/schemas/CategoryRef' description: Categories the creator actually sells in, ranked by revenue share. agency: type: - string - 'null' description: Talent network or MCN, where the channel discloses one. metrics: $ref: '#/components/schemas/CreatorMetrics' period: $ref: '#/components/schemas/ResolvedPeriod' currency: type: string meta: $ref: '#/components/schemas/DataMeta' ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' Channel: type: string description: > 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. enum: - tiktok_shop examples: - tiktok_shop Market: type: string description: An ISO 3166-1 alpha-2 country code identifying a channel storefront. enum: - US - GB - IE - ES - FR - DE - IT - ID - TH - VN - MY - PH - SG - JP - BR - MX examples: - US Period: type: object description: > 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. properties: preset: $ref: '#/components/schemas/PeriodPreset' start: type: string format: date description: First day inclusive.: null end: type: string format: date description: Last day inclusive.: null examples: - preset: last_30d - start: '2026-08-01' end: '2026-08-31' SortSpec: type: object required: - field properties: field: type: string description: >- A metric or attribute name. Sortable fields are listed on each entity in the [metrics reference](/docs/concepts/metrics). direction: type: string enum: - asc - desc default: desc examples: - field: revenue direction: desc NumberRange: type: object description: >- An inclusive or exclusive numeric bound. Combine keys to express a closed range. properties: gte: type: number gt: type: number lte: type: number lt: type: number examples: - gte: 15 lte: 45 ResolvedPeriod: type: object description: > 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. required: - start - end properties: start: type: string format: date end: type: string format: date granularity: type: string enum: - day - week - month description: The smallest bucket the channel reports for this market. adjusted: type: boolean description: > True when the requested dates were snapped to the nearest boundary the channel supports. See [Periods and currency](/docs/concepts/periods). CategoryRef: type: object properties: id: type: string examples: - cat_beauty_personal_care name: type: string examples: - Beauty & Personal Care path: type: array items: type: string description: Names from the root down to this category. CreatorMetrics: type: object properties: revenue: type: number description: Revenue attributed to the creator's content. units_sold: type: integer gpm: type: number description: Gross revenue per thousand views. avg_commission_rate: type: number products_count: type: integer description: Distinct products the creator sold. shops_count: type: integer videos_count: type: integer livestreams_count: type: integer avg_views_per_video: type: number engagement_rate: type: number description: Likes comments and shares divided by views.: null follower_growth: type: integer description: Net followers gained over the period. DataMeta: type: object description: How current and how complete this record is. properties: refreshed_at: type: string format: date-time description: When Unif last refreshed this record. completeness: type: number minimum: 0 maximum: 1 description: Share of the requested fields that were populated. missing_fields: type: array items: type: string description: Fields that are not covered for this channel and market. Error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - billing_error - coverage_error - api_error code: type: string examples: - parameter_invalid message: type: string param: type: - string - 'null' description: The offending field as a dot-path.: null doc_url: type: string format: uri request_id: type: string PeriodPreset: type: string enum: - last_7d - last_30d - last_90d - last_180d - month_to_date - previous_month default: last_30d responses: BadRequest: description: The request was malformed or a parameter was invalid. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: 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 InsufficientCredits: description: The workspace has no credits left for this billing period. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: 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 RateLimited: description: Too many requests. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: RequestId: description: Unique ID for this request. Include it in support conversations. schema: type: string RetryAfter: description: Seconds to wait before retrying. schema: type: integer RateLimitLimit: description: Requests allowed in the current window. schema: type: integer RateLimitRemaining: description: Requests left in the current window. schema: type: integer RateLimitReset: description: Unix timestamp when the window resets. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: > Send your workspace API key as a bearer token: ``` Authorization: Bearer unif_sk_live_... ``` Keys are scoped to a single workspace. See [Authentication](/docs/authentication). ````