---
title: "Batch creator lookup"
method: POST
path: "/v1/satellite/creators/batch"
tags: ["Satellite"]
---

# Batch creator lookup

`POST /v1/satellite/creators/batch`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/satellite/creators/batch`
- Auth: HTTP bearer

Submit up to 25 creators for parallel lookup. Returns a batch_id with per-creator job IDs. Poll aggregate status via GET /v1/satellite/creators/batch/:batch_id, or individual jobs via GET /v1/satellite/creator/status/:job_id. Pricing: $0.50 per creator that starts a lookup, plus the audience surcharge per creator when audience flags are set. A creator answered from the 6-hour cache comes back completed and is free, as on the single lookup. A creator whose lookup fails (for example a handle with no public posts) is refunded; its failed status reports credits_refunded.

## Request body

- BatchCreatorLookupDto
  - `creators` BatchCreatorItemDto[], required: Array of creators to look up (max 25 per batch)
    - `platform` 'tiktok' | 'youtube' | 'instagram', required
    - `username` string, required: Creator handle (without leading @)
  - `include` string: Comma-separated list of optional fields to include: "videos", "outliers"
  - `cross_links` boolean: Enable cross-platform link discovery for all creators in the batch.
  - `max_videos` number: Number of videos to fetch per creator
  - `outlier_threshold` number: Outlier detection threshold multiplier
  - `audience_demographics` boolean: Include inferred audience demographics for every creator in the batch. Cache-first; misses dispatch async snapshot jobs and add an extra $0.50 surcharge per creator on top of the $0.50-per-creator batch cost. Cache hits are free. Off by default.
  - `audience_geography` boolean: Include inferred audience geography for every creator in the batch. Same caching and $0.50-per-creator surcharge behavior as audience_demographics; cache hits are free. Off by default.
  - `freshness_days` number: Maximum age (in days) of an acceptable cached audience snapshot. Only used when audience flags are set.

## Response `202`

Batch submitted

- BatchLookupResponseDto
  - `data` BatchLookupResultDto, required
    - `batch_id` string, required
    - `status` 'processing' | 'completed' | 'partial' | 'failed', required
    - `total` number, required
    - `completed` number, required
    - `failed` number, required
    - `processing` number, required
    - `creators` BatchCreatorJobItemDto[], required
      - `platform` string, required
      - `username` string, required
      - `job_id` string, required
      - `status` 'processing' | 'completed' | 'failed', required: "completed" at submit time means the creator was answered from the 6-hour cache and was not billed.

## Other responses

- `400`: Invalid request
- `401`: Unauthorized - missing or invalid API key
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

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