---
title: "Bulk lookup (≤100 creators)"
method: POST
path: "/creators/bulk"
---

# Bulk lookup (≤100 creators)

`POST /creators/bulk`

## Request

- Base URL: `https://creatorscore.io/api/v1`
- URL: `https://creatorscore.io/api/v1/creators/bulk`
- Auth: API key in header `X-API-Key`

## Headers

- `Idempotency-Key` string
- `X-Customer-Ref` string

## Request body

- object
  - `creators` object[], required
    - `platform` string, required
    - `handle` string, required
  - `cache_only` boolean: When true, never trigger fresh scrapes for this batch. Cache hits return inline (flat cached fee each); misses return status='not_scored' instead of being queued. Lets a caller enrich a roster with existing scores without spending on scrapes.

## Response `200`

Per-creator result (cached / queued / error). Atomic credit accounting; duplicates within the same batch are charged once.

- object
  - `results` object[]
  - `summary` object
    - `total` integer
    - `cached` integer
    - `queued` integer
    - `errored` integer
    - `credits_spent` integer
    - `credits_remaining` integer

## Other responses

- `400`: Invalid request body.
- `401`: Missing or invalid API key.
- `429`: Per-key rate limit hit (120 req/min). Retry after the duration in the Retry-After header.

---

[API](https://skmtc.dev/creatorscore/apis/creatorscore-api.md) · [All operations](https://skmtc.dev/creatorscore/apis/creatorscore-api/llms.txt) · [OpenAPI document](https://skmtc.dev/creatorscore/apis/creatorscore-api/revisions/d3a219842277?raw)