{"openapi":"3.0.3","info":{"title":"Favikon Public API","version":"1.0.0","description":"The Favikon Public API gives users programmatic access to Favikon's\ncreator intelligence: enrich a creator from a handle, find lookalikes\nof creators you like, find the creators who post about a brand,\norganize creators into lists, manage campaign rosters, and read\ncampaign-level analytics.\n\nAccess comes in two layers, both enabled per **workspace**:\n\n- **The API add-on** unlocks the **Core API**: enrich, creator profiles,\n  lists, campaigns and their posts. It is bought as an add-on, or\n  arranged by your Favikon contact. Without it every call answers\n  `403 api_access_disabled`.\n- **The Discovery add-on**, on top of it, unlocks the **Discovery API**:\n  creator and content search, the rankings boards, the filter lists,\n  lookalikes, Radar, segments and trackers (see \"The Discovery add-on\"\n  below). It is arranged by your Favikon contact. Without it those calls\n  answer `403 api_discovery_disabled`; the Core API keeps working.\n\nThe sidebar follows the same split, under the headings **Core API** and\n**Discovery API**, and every Discovery API operation carries a\n**Discovery add-on** badge.\n\nWorkspace owners and admins create keys under **Settings → Connections\n→ API Access**, which also shows whether Discovery is on and how much of\ntoday's Discovery quota is left. A key belongs to its workspace: that\nworkspace's credits pay for paid calls, and its CRM is what `in_crm` /\n`hide_saved` refer to.\n\n## Quickstart\n\nFind creators, enrich the best ones, keep them in a list and track what\nthey post. Steps 1 and 4 (search, track) need the Discovery add-on.\n\n1. **Search**: `POST /api/v1/search/creators` with\n   `{ \"prompt\": \"vegan chefs in Paris\", \"per_page\": 25 }` returns 25\n   `CreatorCard`s, best match first. **1 credit.**\n2. **Enrich the top 10**: `POST /api/v1/enrich/bulk` with\n   `{ \"items\": [{ \"creatorId\": \"<creator_id>\" }, …] }` (the first 10\n   `creator_id`s), then poll `GET /api/v1/enrich/bulk/{bulkId}` until\n   `data.all_complete` is `true`. **3 credits per creator enriched**, 0\n   inside a creator's 30-day access window, so at most 30.\n3. **Keep them in a list**: `POST /api/v1/lists` with\n   `{ \"name\": \"Vegan chefs — Paris\" }`, then\n   `POST /api/v1/lists/{listId}/contacts` with\n   `{ \"creator_ids\": [ … the same 10 … ] }`. **Free.**\n4. **Track them**: `POST /api/v1/trackers` with\n   `{ \"list_id\": \"<list_id>\", \"name\": \"Vegan chefs — weekly\" }`. The\n   leaderboard (`GET /api/v1/trackers/{trackerId}/creators`) and the\n   posts feed (`GET /api/v1/trackers/{trackerId}/posts`) fill up as the\n   creators post. **No credits**: the 10 creators take 10 spots of the\n   monthly tracked-creator quota (`409 tracker_limit_reached` when it's\n   full).\n\nThe whole run costs **at most 31 credits**. Each request body above is\nthe `quickstart` example of its endpoint. As one script (bash + jq):\n\n```bash\nAPI=https://listening-api.favikon.com/api/v1\nAUTH=\"Authorization: Bearer $FAVIKON_API_KEY\"\nJSON=\"Content-Type: application/json\"\n\n# 1. Search, keep the top 10 ids\nids=$(curl -s -X POST \"$API/search/creators\" -H \"$AUTH\" -H \"$JSON\" \\\n  -d '{\"prompt\":\"vegan chefs in Paris\",\"per_page\":25}' | jq -c '[.data[:10][].creator_id]')\n\n# 2. Enrich them, wait until every enrichment is done\nbulk=$(curl -s -X POST \"$API/enrich/bulk\" -H \"$AUTH\" -H \"$JSON\" \\\n  -d \"$(jq -n --argjson ids \"$ids\" '{items: [$ids[] | {creatorId: .}]}')\" | jq -r .data.bulk_id)\nuntil curl -s \"$API/enrich/bulk/$bulk\" -H \"$AUTH\" | jq -e .data.all_complete > /dev/null; do sleep 5; done\n\n# 3. Keep them in a list\nlist=$(curl -s -X POST \"$API/lists\" -H \"$AUTH\" -H \"$JSON\" \\\n  -d '{\"name\":\"Vegan chefs — Paris\"}' | jq -r .data.list_id)\ncurl -s -X POST \"$API/lists/$list/contacts\" -H \"$AUTH\" -H \"$JSON\" \\\n  -d \"$(jq -n --argjson ids \"$ids\" '{creator_ids: $ids}')\" > /dev/null\n\n# 4. Track them\ncurl -s -X POST \"$API/trackers\" -H \"$AUTH\" -H \"$JSON\" \\\n  -d \"$(jq -n --arg list \"$list\" '{list_id: $list, name: \"Vegan chefs — weekly\"}')\" | jq .data\n```\n\n### More to explore\n\n- **Enrich one creator from a handle**: `POST /api/v1/enrich` with\n  `{ \"instagramHandle\": \"bianca.d\" }`, then poll\n  `GET /api/v1/enrich/{enrichmentId}` until `status` is `done`.\n- **Find similar creators** (Discovery add-on): `POST /api/v1/lookalikes`\n  with `{ \"seeds\": [\"<creator_id>\", { \"instagramHandle\": \"bianca.d\" }] }`.\n- **Find who posts about a brand** (Discovery add-on):\n  `POST /api/v1/radar` with `{ \"brands\": [{ \"instagramHandle\": \"nike\" }] }`;\n  each creator comes with a `mention_count`, and\n  `GET /api/v1/radar/{radarSearchId}/creators/{creatorId}/posts` returns\n  the posts behind it.\n- **Search posts and read the boards** (Discovery add-on):\n  `POST /api/v1/search/content`, `GET /api/v1/rankings/creators`,\n  `GET /api/v1/rankings/brands`, and the `GET /api/v1/filters/*` lists\n  of every accepted filter value.\n- **Run campaigns**: `POST /api/v1/campaigns/{campaignId}/creators`, then\n  `GET /api/v1/campaigns/{campaignId}/analytics` and\n  `GET /api/v1/campaigns/{campaignId}/posts`.\n- **Keep a search fresh** (Discovery add-on): a segment\n  (`POST /api/v1/segments`) saves a search as a list that refreshes\n  every day.\n\n## Authentication\n\nAll requests require an API key, as a Bearer token or an `X-API-Key`\nheader:\n```\nAuthorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\nX-API-Key: fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\n```\nGenerate one in the dashboard under **Settings → Connections → API Access**.\nA `401` is returned for missing, malformed, or revoked keys. A `403` is\nreturned when the key is valid but access is blocked:\n`api_access_disabled` (the workspace's API add-on is not active),\n`api_discovery_disabled` (a Discovery API call, and the workspace\ndoesn't have the Discovery add-on), `user_banned` (suspended account),\n`account_pending_deletion`, `key_owner_not_member` or\n`key_owner_not_admin`. See \"Errors\" for the full list.\n\nA key acts as the workspace member who created it, and only works while\nthat member is still an **owner or admin** of the workspace. When they\nleave the workspace or are demoted below admin, their keys are revoked\nand every call answers `403 key_owner_not_member` /\n`403 key_owner_not_admin`. Ask a current owner or admin for a new key.\n\n## The Discovery add-on\n\nEvery endpoint of the **Discovery API** needs the **Discovery add-on**,\nenabled per workspace by your Favikon contact on top of the API add-on:\ncreator search, content search, the rankings boards and the filter lists\n(`/search/*`, `/rankings/*`, `/filters/*`), lookalikes (`/lookalikes`),\nRadar (`/radar/*`), segments (`/segments/*`) and trackers\n(`/trackers/*`). Without the add-on every one of these calls answers\n`403 api_discovery_disabled`, before any rate limit or charge, and an\nexisting segment or tracker can't be read, paused or deleted through the\nAPI either. The Core API keeps working. Each of these operations carries\na **Discovery add-on** badge.\n\n- **Same engine as the app, at Pro level.** Searches, rankings and filter\n  lists answer as for a Pro plan, whatever the workspace's plan (Core,\n  trial…).\n- **One creator card, one post format.** Creators come back as a\n  `CreatorCard` (social links, score, followers, language, gender,\n  country, age, job title, company, description, industry, niches, up\n  to 5 associated brands — never an email or a phone number, not even\n  inside the free-text fields); posts as a `PostSummary`, each\n  embedding its creator's card.\n- **Cursors.** Search pages are cursor-paged: see \"Cursor pagination\".\n- **Limits.** A search returns at most **1,000 results** (40 pages of\n  25; 20 pages of 50 on Radar) — a cursor past that answers\n  `429 search_result_limit`. A\n  workspace can pull **10,000 results per day** (UTC) across the\n  Discovery searches (your Favikon contact can change it); a page that\n  would go over answers `429 daily_result_limit` with a `Retry-After`\n  until midnight UTC, and nothing is charged. Creator search, content\n  search and Radar pages count once: fetching the same page again is\n  free and not counted. A rankings page counts on every read.\n  `meta.usage` shows where the workspace stands, and so does\n  **Settings → Connections → API Access**. The filter lists, lookalikes,\n  segments and trackers don't count.\n- **Fetching new creators.** Endpoints that take handles fetch a creator\n  Favikon doesn't know yet from its network. A workspace can fetch\n  **500 new creators per day** (UTC); creators already in Favikon never\n  count. See \"Resolving handles\".\n- **Seed analyses.** A lookalike seed Favikon hasn't analysed yet is\n  analysed when you first use it. A workspace can start **100 seed\n  analyses per day** (UTC), across `POST /lookalikes` and lookalike\n  segments; past it the call answers `429 seed_analysis_limit_reached`\n  until midnight UTC. Seeds already analysed never count.\n- **Nothing runs before the credit check.** A workspace that can't pay\n  for a search gets its `402` before any handle is fetched or any seed\n  analysed.\n\n## Rate Limiting\n\n- **20 units per 2 seconds** per API key. A call counts as **1** unit,\n  except these, which count as **5** (4 per 2 seconds):\n  - `POST /search/creators`, `POST /search/content`\n  - `GET /rankings/creators`, `GET /rankings/brands`\n  - `POST /lookalikes`, `POST /radar`\n  - `POST /segments/{segmentId}/count`, `POST /segments/{segmentId}/commit`\n  - `GET /trackers/{trackerId}/creators`, `GET /trackers/{trackerId}/posts`\n- Headers on every response:\n  - `X-RateLimit-Limit` — units per window\n  - `X-RateLimit-Remaining` — units left in this window\n  - `X-RateLimit-Reset` — ISO timestamp when the window resets\n- On exceed: `429 rate_limit_exceeded` with a `Retry-After` header\n  (seconds). A refused call still counts against the window.\n- **API-wide capacity.** The searches that run the search engine — a\n  new `POST /search/creators`, `POST /search/content`, `POST /lookalikes`\n  or `POST /radar` search, and a later creator or content page that needs\n  another engine run — share a cap on how many run at once, across every\n  key. A workspace also runs **one search of each kind at a time** (one\n  creator search, one content search, one lookalikes search, one Radar\n  search), across all its keys. Past either cap the call answers\n  `503 search_busy` at once, with a `Retry-After` header: nothing ran,\n  and nothing is charged or counted. Retry after `Retry-After` seconds,\n  or wait for your own running search to finish. Cursor pages read from\n  a saved search never wait for it.\n\n## Common Patterns\n\n### Async + polling (`/enrich`, and seeds / brands still being fetched)\n`POST /api/v1/enrich` returns 200 immediately with `status: \"pending\"`\nand an `enrichment_id`; a worker runs the pipeline in the background —\npoll `GET /api/v1/enrich/{id}` until `status` is `done` or `failed`.\nThe only case where the POST itself returns `done` is submitting the\nexact same input twice within 30 seconds: the duplicate call reuses\nthe prior request's record (idempotency) instead of starting a new\nrun. Bulk enrich uses the same pattern with a shared `bulk_id`\nyou can poll via `GET /api/v1/enrich/bulk/{bulk_id}`.\n\n`POST /lookalikes` and `POST /radar` answer **`202`** with a\n`Retry-After` header while a creator you passed by handle is still\nbeing fetched (or, for lookalike seeds, analysed). Nothing is charged;\nsend the same request again after `Retry-After` seconds.\n\n### Pagination\nList endpoints page with `?page=N&per_page=K` (1-indexed, `per_page` up\nto 100). Responses carry `meta.page`, `meta.per_page`, `meta.total` and\n`meta.total_pages`.\n\n### Cursor pagination\nSearches and the tracker posts feed page with an opaque **cursor**\ninstead. The first call runs the search and saves it; every page carries\n`meta.pagination` (`page`, `page_size`, `total`, `has_more`,\n`next_cursor`), and you send `next_cursor` back for the next page until\n`has_more` is `false` and `next_cursor` is `null`. A cursor page never\nre-runs the search, so the pages stay consistent, with no duplicates.\n\n| Calls | Send the cursor as | Kept | When it's gone |\n|---|---|---|---|\n| `POST /search/creators`, `POST /search/content` | `{ \"cursor\": \"…\" }` (the rest of the body is ignored) | 24 hours, for the workspace that ran the search | `410 search_expired`; another workspace's: `404 search_not_found` |\n| `POST /lookalikes` | `{ \"cursor\": \"…\" }` (the rest of the body is ignored) | 1 hour | `404 search_expired` |\n| `POST /radar` | `{ \"cursor\": \"…\" }` | 24 hours | `404 radar_search_not_found` |\n| `GET /trackers/{trackerId}/posts` | `?cursor=…`, alone | 10 minutes after the call that returned it | `410 search_expired`; unknown: `404 search_not_found` |\n\nCursors are signed. Send `next_cursor` back exactly as you got it: a\ncursor this API didn't issue, an edited one, or one issued before the\ncurrent version of the API answers `422 invalid_cursor` (run the search\nagain). Content search only serves the page after one it already served:\na cursor that skips ahead is `422 invalid_cursor` too.\n\n- **The first call sets the page size**: `per_page` on\n  `/search/creators` (1–100) and on the tracker feed (1–100, default\n  25); 50 on `/radar`; 25 everywhere else.\n- **Discovery searches stop at 1,000 results** (Radar keeps at most\n  1,000 creators): a cursor past them answers `429 search_result_limit`.\n  Narrow the search instead.\n- **What a page costs**: a creator search, content search, lookalikes or\n  Radar page is charged the first time it is served, and fetching the\n  same cursor again is free. The tracker feed is free. See \"Credits\".\n- **A page another request is fetching**: if two requests ask for the\n  same new page at once, one fetches it and the other answers\n  `503 page_pending` with `Retry-After: 2`. Nothing was charged; retry\n  and you get the page for free.\n- **The tracker feed's last page closes it**: replaying the last page's\n  cursor answers `410 search_expired`. A workspace keeps at most **10\n  feeds** open: starting an 11th closes the one paged least recently,\n  and its next cursor answers `410 search_expired`.\n\n```js\n// Every page of a creator search.\nlet body = { prompt: \"vegan chefs in Paris\" };\nfor (;;) {\n  const page = await fetch(`${API}/search/creators`, {\n    method: \"POST\",\n    headers: { Authorization: `Bearer ${KEY}`, \"Content-Type\": \"application/json\" },\n    body: JSON.stringify(body),\n  }).then((res) => res.json());\n  handle(page.data);\n  if (!page.meta.pagination.has_more) break;\n  body = { cursor: page.meta.pagination.next_cursor };\n}\n```\n\n### Bulk + per-item status\nAdd/remove endpoints accept arrays (max 100 items per request) and\nreturn per-item outcomes (`added`, `already_in_list`, `not_found`,\n`failed`, …). Status codes:\n- `201` — every item succeeded\n- `207` — mixed outcomes (inspect `summary` and per-item `status`)\n- `400` — every item failed\n- `404` — every item was unknown\n- `409` — every item was already present (idempotent collision)\n\n### Credits\nPaid calls, charged to the key's workspace:\n\n| Call | Cost |\n|---|---|\n| `POST /api/v1/enrich` | 3 per successful enrichment; 2 when the workspace already has preview access to the creator; 0 inside the 30-day access window |\n| `POST /api/v1/enrich/bulk` | 3 per item that enriches successfully; 2 with preview access to that creator; 0 inside its 30-day access window |\n| `POST /api/v1/lookalikes` | 2 per page, charged once per page of a search |\n| `POST /api/v1/radar` | 2 per page of 50, charged once per page (a search with no results is free) |\n| `POST /api/v1/search/creators` | Like the app: 1 per 25 of `per_page` for a page with results (25 → 1, 100 → 4), charged once per page of a search |\n| `POST /api/v1/search/content` | 1 per page of 25 with results, charged once per page of a search |\n| `GET /api/v1/rankings/creators`, `GET /api/v1/rankings/brands` | 1 per 25 rows returned, on every read (a page of 50 costs 2; a whole 200-row board at most 8) |\n| `POST /api/v1/segments/{segmentId}/commit` | The price `POST /segments/{segmentId}/count` quotes: 1 per 25 creators of `size_limit` (Radar and lookalikes: × 2 per brand or seed). Committing twice charges once |\n| Segment renewal (every 30 days, active segments) | The commit price again, charged to the segment's workspace; a renewal it can't pay pauses the segment |\n| `POST /api/v1/segments/{segmentId}/resume` | The renewal price, only when the paid 30-day period has lapsed; free inside it |\n\n\"Charged once per page\" means per page of **one search**: fetching the\nsame `cursor` again is free, but sending the same body again starts a\nnew search and is charged again.\n\n`POST /api/v1/enrich` respects the same 30-day customer-profile-access\nwindow the dashboard uses, so re-enriching a creator you already paid\nfor (via the dashboard or a previous API call) costs **0 credits**, and\none the workspace has only previewed costs **2** (the preview is paid\nalready; only the full access is charged). The actual charge is\n`meta.credits.cost` on the GET response (`GET /enrich/bulk/{bulkId}`:\nthe batch's total); `meta.credits.cost` on the POST is the maximum\npossible charge. On the\nsearch endpoints `meta.credits.cost` is the price of that call (0 for a\nfree repeat); a workspace with unlimited credits sees the price but is\nnever debited.\nA paid call returns `402 insufficient_credits` before doing any work\nwhen the balance can't cover it. Credits are taken all at once before a\npage is handed out, so concurrent calls can't overspend the balance:\nwhen several draw on it at the same time, the ones it no longer covers\nanswer `402` too, even if the balance looked sufficient when they\nstarted. A `402` never charges anything.\n\nAn enrichment is charged when its run starts (after the creator is\nfound), and refunded if the run then ends `failed`: a failed\nenrichment always shows `meta.credits.cost: 0` and never counts in the\nbulk total.\n\nEverything else — campaigns, lists, creator reads, Radar evidence\nposts, the Discovery filter lists, segment counts and reads, trackers\n— is **free**. Trackers use no credits but a monthly tracked-creator\nquota (`GET /trackers` → `meta.quota`).\n\n### Resolving handles\nEndpoints that accept `handles` (POST /enrich, POST /campaigns/:id/creators,\nPOST /lists/:id/contacts, POST /lists/:id/contacts/bulk-delete) take\nthe same shape — exactly one of `linkedinHandle`, `instagramHandle`,\n`tiktokHandle`, `youtubeHandle`, `xHandle` per item. Each accepts\neither a bare handle (`bianca.d`) or a full URL\n(`https://instagram.com/bianca.d`). Handles may contain letters of\nany alphabet, accents included (`josé-garcía`), digits, `_`, `.` and\n`-`. A URL is checked like a bare handle: a malformed one (a broken\n`%` escape, a path that can't be a handle) is `invalid_input` (400 on\n`POST /enrich`, a `failed` item elsewhere). On add, repeats of the same\nhandle in one request (case-insensitive) are handled once.\n\nOn add/enrich, unknown creators are fetched from the social network\non the fly — fetching alone costs no credits; only enrichment does.\nFetching is limited per workspace:\n\n- **500 new creators per day** (UTC) per workspace. Creators Favikon\n  already knows never count. Past it, a handle that needs a fetch\n  fails with `ingest_limit_reached` until midnight UTC.\n- `ingest_in_progress` — another request is already fetching the same\n  handle. Retry in a few seconds.\n- `ingest_unavailable` — creator lookup is briefly unavailable. Retry\n  in a few seconds (`503` with `Retry-After: 5` where the whole call\n  is refused).\n- A handle the network reported as not found (or deleted, private…)\n  is remembered for **24 hours**: asking again within that time\n  answers the same error without a new fetch.\n\nOn delete, handles only resolve via indexed lookup (no engine call) —\nunknown handles come back as `not_found` since they obviously aren't\nin your list.\n\n`seeds` (`POST /lookalikes`) and `brands` (`POST /radar`) take a\ncreator id or one of these objects per item (plus `{ \"creatorId\": … }`)\n— see the `CreatorRef` schema. There, and in segment rules\n(`POST /segments`, `PATCH /segments/{segmentId}`), a request refused only because\nof the fetch limit answers `429 ingest_limit_reached` (with a\n`Retry-After` until midnight UTC) or `503 ingest_unavailable`, and\nnothing is charged.\n\n## Response Envelope\n\nSuccessful responses:\n```json\n{\n  \"data\": { ... },\n  \"meta\": {\n    \"api_version\": \"v1\",\n    \"page\": 1,\n    \"per_page\": 20,\n    \"total\": 100,\n    \"total_pages\": 5\n  }\n}\n```\n\nErrors:\n```json\n{\n  \"error\": {\n    \"code\": \"invalid_parameters\",\n    \"message\": \"Invalid campaign ID\",\n    \"status\": 422,\n    \"details\": [{ \"field\": \"campaignId\", \"reason\": \"Must be a valid ID\" }]\n  }\n}\n```\n\n## Errors\n\nEvery error uses the envelope above. These come from the key check and\nthe rate limiter, which run before the endpoint itself, so **any\nendpoint** can answer them:\n\n| Status | Code | Meaning |\n|---|---|---|\n| 401 | `missing_api_key` | No key in `Authorization: Bearer` or `X-API-Key` |\n| 401 | `invalid_api_key` | Not a `fav_` key, revoked, or its workspace no longer exists |\n| 401 | `key_not_scoped` | A key minted before workspaces existed — regenerate it |\n| 403 | `api_access_disabled` | The workspace doesn't have the API add-on |\n| 403 | `user_banned` | The key's owner is suspended |\n| 403 | `account_pending_deletion` | The key's owner is scheduled for deletion |\n| 403 | `key_owner_not_member` | The key's owner is no longer an active member of its workspace — ask an owner or admin for a new key |\n| 403 | `key_owner_not_admin` | The key's owner is no longer an owner or admin of its workspace — ask an owner or admin for a new key |\n| 429 | `rate_limit_exceeded` | Over 20 units per 2 seconds — wait `Retry-After` seconds |\n| 500 | `internal_error` | An unexpected failure on our side — retry |\n| 500 | `authentication_error` | The key could not be checked — retry |\n\nEndpoint-specific codes (`insufficient_credits`, `invalid_cursor`,\n`daily_result_limit`, `search_busy`, `tracker_limit_reached`, …) are listed, each with\nan example, under the endpoint's responses. `search_expired` is **410**\non the Discovery searches and the tracker feed, but **404** on\n`POST /lookalikes`.\n\nErrors raised by shared code with no code of their own carry the generic\ncode of their status: `invalid_input` (400), `unauthorized` (401),\n`insufficient_credits` (402), `forbidden` (403), `not_found` (404),\n`conflict` (409), `gone` (410), `invalid_parameters` (422),\n`rate_limit_exceeded` (429), `service_unavailable` (503). Branch on\nthe HTTP status first, then on `code`.\n\n## Media URLs\n\nCreator avatars and post media (images, videos, thumbnails) are\npre-signed S3 URLs valid for **7 days**. Other URLs are returned as-is.\nThey're freshly signed every time the endpoint is called — re-fetch\nthe parent endpoint to get fresh URLs.\n\n## Data Freshness\n\n- **Enrich** results are computed from Favikon's creator database at\n  the time the worker ran. `last_refreshed_at` marks that compute —\n  the underlying platform data can be older, since Favikon's engine\n  refreshes each network on its own freshness policy. The snapshot is\n  frozen on the enrichment record for 30 days, then 410 Gone (use\n  `/creators/{id}` for the current view while your access window is\n  open — each read also triggers the same background refresh as the\n  app's Refresh button).\n- **Campaign analytics** includes `meta.last_synced_at` showing\n  the most recent sync from tracked posts. Sync cadence depends on\n  campaign type (typically every few hours).\n- **Lists & campaign creators** are real-time — every read hits the\n  database directly.\n\n## Ratings & ranks\n\n`GET /api/v1/enrich/{enrichmentId}` (once `done`) and\n`GET /api/v1/creators/{creatorId}` carry the ratings and ranks the\nFavikon app shows on the creator's profile, built by the same code — use\nthem as they are rather than deriving your own. They are computed when\nyou read them, never stored on the enrichment record, and cached on\nFavikon's side.\n\n**Ratings** — `data.stats.<platform>.ratings` holds the badges of the\nprofile's Performance tab for that platform over the **last year** (the\nperiod the tab opens on; the other `stats` fields cover the last 90\ndays). Each entry is `{ rating, label, value, peer_median }`:\n\n| Entry | `value` | Compared with |\n|---|---|---|\n| `engagement_rate` | engagement per post ÷ followers × 100 (%) | the peers' median engagement rate — each peer's own |\n| `engagement` | engagement (likes + comments + shares) per post | the peers' median engagement per post |\n| `follower_growth` | follower growth over the year (%) | fixed bands — `peer_median` is `null` |\n| `posting` | posts per `unit` (a month) | the peers' median posts per month |\n\nPeers are ~100 creators similar to this one (niche and follower size),\nmeasured over the same year with the same formula. The difference from\nthe peer median gives the rating:\n\n| `rating` | `label` | vs. peer median | `follower_growth` |\n|---|---|---|---|\n| `excellent` | Excellent | +20 % or more | +20 % or more |\n| `good` | Good | +5 % to +20 % | +10 % to +20 % |\n| `average` | Average | −15 % to +5 % | 0 to +10 % |\n| `below_average` | Below Average | −30 % to −15 % | 0 to −10 % |\n| `poor` | Poor | −50 % to −30 % | −10 % to −20 % |\n| `very_poor` | Very Poor | below −50 % | below −20 % |\n\nAn entry is `null` when the app shows no badge for it (no peers with\nposts in the year, no post, too little follower history). `ratings` is\n`null` on a platform without a Performance tab (Twitch, Pinterest,\nSubstack) and while it is still computing.\n\n`meta.ratings_status` says whether everything was served: `ready`, or\n`deferred` — some ratings could not be computed within this request\n(a heavy creator, or busy capacity); they keep computing, so read again\na few seconds later. It is `null` on an enrichment that isn't `done`. A\nsingle enrichment computes its ratings before it turns `done`, so the\nfirst `done` read normally has them. Ratings are cached up to 24 hours\n(see `computed_at`); a result with no badge at all — typically a creator\nindexed moments ago, whose posts are still arriving — only 1 hour.\n\n**Brand safety** — `data.insights.brand_safety_label` is the app's label\nfor `brand_safety` (0–100): 76–100 `Very Safe`, 50–75 `Safe`, 25–49\n`Caution`, 0–24 `Risky`.\n\n**Ranks** — `data.rankings` lists the creator's best ranking boards, best\nrank first, up to 9: the profile's Rankings card. A board is a network\nand/or a location (a country, or a language worldwide), optionally\nnarrowed to an industry, a niche or a gender. `board.top_id` is the slug\nthe board listing (`GET /api/v1/rankings/creators`, Discovery add-on)\nreports as `meta.top_id`.\n\n- `rank` = the creators on the board with a strictly higher Favikon\n  score, + 1 (ties share a rank). It is the creator's own position —\n  **not limited to the top 200** the board listing returns.\n- `board_size` = the creators on the board; `top_percent` =\n  `max(round(rank ÷ board_size × 100), 1)` — the app's \"Top N%\".\n- Cached up to 12 hours (1 hour while the creator has no ranked board).\n  `[]` when it has none.\n"},"servers":[{"url":"https://listening-api.favikon.com","description":"Production"}],"tags":[{"name":"Enrich","description":"Resolve a handle (or refresh a known creator) into a full Favikon\nprofile — scores, audience demographics, recent posts, AI insights,\npartnered brands, platform handles.\n\n**Use when** you have a social handle or URL and want creator data\nto qualify or score them.\n**Cost** 3 credits per successful enrichment (2 when the workspace\nalready has preview access to the creator), gated by the 30-day\nprofile-access window (see \"Credits\" in Common Patterns).\n**Pattern** Async — POST returns `pending`/`done`; poll the GET\nendpoint until terminal.\n"},{"name":"Creators","description":"Long-lived, always-current reads of creators your workspace already\nunlocked — by `creator_id` alone, no enrichment id needed.\n\n**Use when** you enriched a creator (or unlocked them in the app)\nwithin the last 30 days and want their current data without creating\na new enrichment.\n**Cost** Free while the 30-day access window is open; `402` after.\n**Pattern** Synchronous GET. Each call also triggers the same free\nbackground stats refresh as the app's Refresh button (throttled to\nonce per hour per creator).\n"},{"name":"Lists","description":"Saved groupings of contacts — your CRM-lite view. Create lists,\nadd or remove creators (by id or handle), browse contents.\n\n**Use when** organizing creators outside of any specific campaign\n(e.g. shortlists, segments, audit groups).\n**Cost** Free. Adding by handle ingests unknown creators from the\nnetwork for free; only `/enrich` consumes credits.\n**See also** `Campaigns` for tracked-campaign rosters.\n\nThe list behind a segment belongs to the segment: it isn't returned by\n`GET /lists`, and every list endpoint answers `404` for it. Read its\nmembers with `GET /segments/{segmentId}/creators`.\n"},{"name":"Campaigns","description":"Everything to do *with* a campaign: read its analytics, manage the\ncreators in its roster, query per-creator performance.\n\n**Use when** building dashboards, syncing performance to BI,\ngenerating reports, or programmatically managing the roster of a\ntracked campaign.\n**Cost** Free. Adding creators by handle ingests unknown creators\nfor free; only `/enrich` consumes credits.\n**Freshness** Analytics responses include `meta.last_synced_at`;\nroster reads are real-time.\n"},{"name":"Posts","description":"Read post content and metrics for a specific tracked campaign.\n\n**Use when** ingesting tracked-campaign posts into external tools,\nor querying engagement / EMV / impressions per post.\n**Cost** Free.\n**Freshness** Mirrors the campaign sync cadence.\n"},{"name":"Discovery","description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it every call in this section answers\n> `403 api_discovery_disabled`.\n\nSearch creators by what they do (a natural-language prompt and/or\nfilters) and content by what it says (keywords and/or filters) — the\nsame engines as the app — read favikon.com's rankings, and list the\naccepted filter values.\n\n**Use when** prospecting: finding creators for a brief, the posts\nabout a topic and who made them, or the top creators of a niche.\n**Cost** Searches: 1 credit per 25 of page size per page with results,\ncharged once per page. Rankings: 1 credit per 25 rows, every read.\nFilter lists free.\n**Pattern** Cursor-paged searches; page-numbered rankings.\n"},{"name":"Lookalikes","description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it every call in this section answers\n> `403 api_discovery_disabled`.\n\nCreators similar to creators you pick — by bio and content, ranked\nbest match first, with filters on location, language, platforms and\naudience size.\n\n**Use when** you have a few creators that fit and want more like them.\n**Cost** 2 credits per page of 25, charged once per page.\n**Pattern** Cursor-paged search; `202` while new seeds are analysed.\n"},{"name":"Radar","description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it every call in this section answers\n> `403 api_discovery_disabled`.\n\nThe creators who posted about one or more brands, ranked by how many\nposts mention them — plus the posts themselves as evidence.\n\n**Use when** looking for creators already talking about a brand (yours\nor a competitor's).\n**Cost** 2 credits per page of 50, charged once per page; evidence\nposts cost no credits. Each page's creators count once toward the workspace's daily\nDiscovery results quota.\n**Coverage** Mentions on Instagram, TikTok, X and LinkedIn.\n"},{"name":"Segments","description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it every call in this section answers\n> `403 api_discovery_disabled`.\n\nA saved search that refreshes every day and keeps a list of its\nmembers: creator search, content search, lookalikes, Radar or a\nranking, with exclusions.\n\n**Use when** you want a list of creators that stays matched to a\nbrief — new matches come in, creators who stop matching leave.\n**Cost** Creating, counting and reading are free. Committing costs\nthe price `POST /segments/{id}/count` quotes (1 credit per 25 creators\nof `size_limit`; Radar and lookalikes × 2 per brand or seed), charged\nagain every 30 days while the segment is active. Pausing stops the\nrenewal.\n**Pattern** Create (draft) → count (free price quote) → commit with\n`confirm_cost` → read `/creators` or track it.\n**Deleting a segment also deletes its list.**\n"},{"name":"Trackers","description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it every call in this section answers\n> `403 api_discovery_disabled`.\n\nFollow the creators of a list or a segment: a leaderboard of their\nnumbers over a period, and the feed of their posts.\n\n**Use when** monitoring a set of creators — competitors, ambassadors,\na segment — over time.\n**Cost** No credits. Each creator tracked during a calendar month\ntakes a spot of the workspace's monthly tracked-creator quota\n(`GET /trackers` → `meta.quota`) until the 1st of next month (UTC),\neven if the tracker is paused or deleted.\n**Pattern** Page-numbered leaderboard; cursor-paged posts feed.\n\n**A tracker follows its source.** A tracker on a list picks up the\ncreators added to the list while the monthly quota lasts; creators\nadded past it stay in the list but aren't tracked. A tracker whose\nlist or segment is deleted — or whose segment lapses because its\nrenewal couldn't be paid — is paused; it keeps its creators and can\nbe resumed.\n"}],"x-tagGroups":[{"name":"Core API","tags":["Enrich","Creators","Lists","Campaigns","Posts"]},{"name":"Discovery API","tags":["Discovery","Lookalikes","Radar","Segments","Trackers"]}],"security":[{"BearerAuth":[]}],"paths":{"/api/v1/enrich":{"post":{"tags":["Enrich"],"summary":"Enrich a single creator (async)","operationId":"enrichCreator","x-rate-weight":1,"x-credits":{"price":3,"per":"enrichment","when":"on_success"},"description":"Submit a creator handle or URL and get back a full Favikon profile —\nscores, audience demographics, recent posts, AI insights, partnered\nbrands, platform handles. Asynchronous: the POST always returns\nimmediately with `status: \"pending\"` and an `enrichment_id` (the one\nexception: an identical request within 30 seconds reuses the prior\nrecord — idempotency — and can come back `done`). A background\nworker runs the same pipeline the dashboard uses; poll\n`GET /api/v1/enrich/{enrichmentId}` until `status` is `done` or\n`failed`.\n\n**Cost** 3 credits per successful enrichment. **2 credits** when the\nworkspace already has preview access to the creator (a profile\npreviewed in the dashboard): the preview is paid already, only the\nfull access is charged. The POST checks the balance against this\ncreator's actual price (0, 2 or 3) and answers `402` when it can't\ncover it. The credits are taken when the run starts, once the\ncreator is found; a run that ends `failed` (creator not found,\npipeline failure, timeout) is refunded in full.\n\n**No double-charging.** If you've already paid for this creator's\nprofile within the last 30 days — via a dashboard profile view OR a\nprevious API enrich — the run is **free** (`meta.credits.cost: 0` on\nthe GET). The charge is gated by the same customer-profile-access\nwindow the dashboard uses. Read `meta.credits.cost` on the GET\nresponse for the actual charge; `meta.credits.cost` on this POST is\nthe maximum possible charge.\n\n**Audience demographics** follow the same pricing as the dashboard:\na **charged** enrichment (a fresh 3-credit unlock) includes audience\ndiscovery, exactly like the app's reveal flow. **Free** re-runs\ninside the 30-day window mirror whatever audience your workspace\nalready has (from a previous charged run or a dashboard reveal).\nAudience exists for Instagram / TikTok / YouTube only, and can be\nempty when the platform cannot compute it for a creator.\n\n**Email** works the same way: a charged enrichment also attempts\nemail discovery (the same waterfall the app runs, included in the 3\ncredits). Discovery is asynchronous and can take several minutes —\nthe found email (or a \"searched, not found\" mark) lands on the\ncontact afterwards and shows on subsequent reads\n(`GET /lists/{listId}/contacts` or a later enrichment); this run's\nfrozen snapshot may still show `null`. Free re-runs mirror the email\nyour workspace already has.\n\n**Discovery completion:** if your access window was opened by a\nsurface that doesn't bundle discovery (an in-app profile unlock),\nthe FIRST free enrichment of that creator completes it — audience\nand email discovery run once, still at 0 credits. Later free runs\nmirror as usual. So a paid window always ends up with full data\nafter at most one API enrichment.\n\n**Expectations by network:** discovery quality tracks the creator's\nplatforms. Multi-network creators resolve fast and often; LinkedIn-only\nprofiles have no audience data at all and the lowest email hit-rate —\nan empty result there usually means the data doesn't exist, not that\nthe API skipped it.\n\n**Getting the complete payload:** the enrichment response contains\nwhatever discovery finished before completion. Audience that must be\nfreshly generated, and emails, land minutes later — and\n`GET /enrich/{enrichmentId}` **live-mirrors `email` and `audience`**\nfrom your workspace contact, so simply keep polling the same URL\nuntil they appear. (A free re-enrichment inside your 30-day window\nalso returns everything, if you prefer a fresh full snapshot.)\n\n**Input** provide exactly one of:\n- `creatorId` — a Favikon GlobalInfluencer id (from\n  `GET /lists/{id}/contacts`, `GET /campaigns/{id}/creators`, or a\n  previous enrichment). Skips the handle-lookup roundtrip when\n  you already know the creator.\n- `linkedinHandle`, `instagramHandle`, `tiktokHandle`,\n  `youtubeHandle`, `xHandle` — bare handle (`bianca.d`,\n  `@bianca.d`) or full URL (`https://instagram.com/bianca.d`).\n\n**When it fails** A `failed` enrichment carries `error.code`:\n- `insufficient_credits` — the balance no longer covered the run\n  when it started (other calls spent it meanwhile).\n- `key_owner_cannot_spend` — the key's owner can no longer spend\n  the workspace's credits. Use a key of a current owner or admin.\n- `creator_not_found` — no creator behind the handle or id; or a\n  network code: `not_found`, `account_deleted`, `private_account`,\n  `restricted_account`, `empty_posts`.\n- `ingest_limit_reached` — the creator had to be fetched from its\n  network and the workspace has fetched its 500 new creators for\n  today. Retry after midnight UTC.\n- `ingest_in_progress` / `ingest_unavailable` — the creator could\n  not be fetched right now. Retry.\n- `key_not_scoped` — the request's key is not scoped to a\n  workspace. Regenerate it.\n- `enrich_pipeline_failure` — the enrichment itself failed or took\n  too long. Retry.\n\nA failed enrichment costs nothing.\n\n**Next steps** Once `status` is `done`, use the resulting\n`creator_id` in `POST /api/v1/lists/{listId}/contacts` (organize) or\n`POST /api/v1/campaigns/{campaignId}/creators` (track in a campaign).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichInput"},"examples":{"creatorId":{"summary":"Refresh a known creator by Favikon id","value":{"creatorId":"6524b53cfa6624efbeeef72a"}},"linkedinHandleAsUrl":{"summary":"LinkedIn profile URL","value":{"linkedinHandle":"https://www.linkedin.com/in/marc-richard/"}},"linkedinHandleBare":{"summary":"LinkedIn bare handle","value":{"linkedinHandle":"marc-richard"}},"instagramHandle":{"summary":"Instagram handle","value":{"instagramHandle":"bianca.d"}},"tiktokHandle":{"summary":"TikTok handle","value":{"tiktokHandle":"@amauryguichon"}}}}}},"responses":{"200":{"description":"Enrichment accepted with status \"pending\" (\"done\" only when an identical request within 30 seconds reused the prior record).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Enrichment"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"enrichmentPending":{"$ref":"#/components/examples/EnrichmentPending"}}}}},"400":{"description":"Invalid input the schema alone can't catch — malformed handle or URL, several identifiers on one item, an identifier type not supported in v1 (`email`), or a `creatorId` whose creator has no indexed network handle (`no_indexed_handle`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidInput":{"summary":"invalid_input","value":{"error":{"code":"invalid_input","message":"Handle cannot be empty.","status":400,"details":[]}}},"noIndexedHandle":{"summary":"no_indexed_handle","value":{"error":{"code":"no_indexed_handle","message":"Creator has no platform handles on file — re-enrichment by id requires at least one indexed network handle.","status":400,"details":[]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found` — the supplied `creatorId` matches no Favikon creator.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFound":{"summary":"not_found","value":{"error":{"code":"not_found","message":"Creator not found: 63a477561c819689ff4e32f8.","status":404,"details":[]}}}}}}},"422":{"description":"`invalid_parameters` — the body doesn't match the schema.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Provide exactly one identifier (linkedinHandle, instagramHandle, tiktokHandle, youtubeHandle, or xHandle).","status":422,"details":[{"field":"xHandle","reason":"Handle contains invalid characters."}]}}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST https://listening-api.favikon.com/api/v1/enrich \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"linkedinHandle\":\"https://www.linkedin.com/in/marc-richard/\"}'\n"},{"lang":"Python","source":"import requests\n\nresponse = requests.post(\n  \"https://listening-api.favikon.com/api/v1/enrich\",\n  headers={\n    \"Authorization\": \"Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n    \"Content-Type\": \"application/json\",\n  },\n  json={\"linkedinHandle\": \"https://www.linkedin.com/in/marc-richard/\"},\n)\ndata = response.json()\n"},{"lang":"JavaScript","source":"const response = await fetch(\n  \"https://listening-api.favikon.com/api/v1/enrich\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: \"Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({ linkedinHandle: \"https://www.linkedin.com/in/marc-richard/\" }),\n  },\n);\nconst data = await response.json();\n"}]}},"/api/v1/enrich/bulk":{"post":{"tags":["Enrich"],"summary":"Enrich up to 100 creators in one request (async)","operationId":"enrichBulk","x-rate-weight":1,"x-credits":{"price":3,"per":"enrichment","when":"on_success"},"description":"Submit 1–100 enrichment inputs in one POST. Each item is tracked\nindependently — its own `enrichment_id` plus a shared `bulk_id`\nyou can use to poll the whole batch at once.\n\n**Cost** 3 credits per successful enrichment; 2 when the workspace\nalready has preview access to that creator; 0 inside its 30-day\naccess window. Invalid inputs (bad handle shape, unsupported network)\ndon't consume credits. The batch's actual total is\n`meta.credits.cost` on `GET /api/v1/enrich/bulk/{bulkId}`.\n\n**Behavior** The response includes a per-item `input` echoing the\nnormalized `(network, username)` so you can pair `enrichment_id`\nback to the handle you submitted. Items that failed input-parsing\ncome back with `enrichment_id: null` and a structured error.\n\n**Next steps** Poll `GET /api/v1/enrich/bulk/{bulk_id}` until\n`all_complete: true`, or poll each `enrichment_id` individually.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/EnrichInput"}}}},"examples":{"threeHandles":{"summary":"Three creators, by URL and handle","value":{"items":[{"linkedinHandle":"https://www.linkedin.com/in/marc-richard/"},{"instagramHandle":"bianca.d"},{"tiktokHandle":"@amauryguichon"}]}},"quickstart":{"summary":"Quickstart: enrich the top 10","value":{"items":[{"creatorId":"656c43ab0c36863cb1ca11c5"},{"creatorId":"62b5e1f0a9c8d7e6f5a4b3c2"},{"creatorId":"61d4c3b2a1f0e9d8c7b6a5f4"},{"creatorId":"63a477561c819689ff4e32f8"},{"creatorId":"6524b53cfa6624efbeeef72a"},{"creatorId":"69bb967146ae23484eb74d66"},{"creatorId":"64a1b2c3d4e5f6a7b8c9d0e1"},{"creatorId":"64a1b2c3d4e5f6a7b8c9d0e2"},{"creatorId":"64a1b2c3d4e5f6a7b8c9d0e3"},{"creatorId":"64a1b2c3d4e5f6a7b8c9d0e4"}]}}}}}},"responses":{"200":{"description":"Bulk request accepted. Each item has its own status.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"bulk_id":{"type":"string"},"enrichments":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"enrichment_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","done","failed"]},"input":{"type":"object","description":"Normalized identifier for this item. Lets you pair the enrichment_id back to the handle you sent.","properties":{"network":{"type":"string","nullable":true,"enum":["instagram","tiktok","youtube","linkedin","twitter",null]},"username":{"type":"string","nullable":true}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"bulkAccepted":{"$ref":"#/components/examples/EnrichBulkAccepted"}}}}},"400":{"description":"`invalid_input` — batch-level input problem: body is not an array, is empty, or exceeds 100 items. Item-level problems (bad handle, insufficient credits for an item) never fail the batch: they surface inside the 200 as items with `status: \"failed\"`, `enrichment_id: null`, `input: { \"network\": null, \"username\": null }` and an `error` (`code`, e.g. `invalid_input` or `insufficient_credits`, and `message`). Pair them with what you sent by `index`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidInput":{"summary":"invalid_input","value":{"error":{"code":"invalid_input","message":"Bulk enrich supports a maximum of 100 items per request.","status":400,"details":[]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/enrich/bulk/{bulkId}":{"get":{"tags":["Enrich"],"summary":"Get every enrichment in a bulk in one request","operationId":"getBulkEnrichment","x-rate-weight":1,"x-credits":{"price":0},"description":"Fetch every enrichment that shares a `bulk_id` in one round-trip.\nNon-blocking: returns the current state immediately — individual\nitems may still be `pending`, just like the single-id GET.\n\n**Cost** Free.\n\n**Behavior** The `summary` rollup (`pending` / `done` / `failed`)\nand `all_complete` flag let clients stop polling without scanning\nevery item. Saves N round-trips compared to fanning out single\nGETs.\n\n**Retention** Same 30-day window as the single endpoint. This\nrollup never returns 410: expired items simply appear with\n`data: null`. Use `/creators/{creator_id}` (or the single-id GET,\nwhich does 410 with a pointer) for the post-expiry story.\n","parameters":[{"name":"bulkId","in":"path","example":"6701a2b3c4d5e6f7a8b9c0f0","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"All enrichments in the bulk + a status rollup.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"bulk_id":{"type":"string"},"total":{"type":"integer"},"all_complete":{"type":"boolean","description":"True when every item is `done` or `failed`. False means the server hit the wait cap before everything finished — re-poll to continue."},"summary":{"type":"object","properties":{"pending":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"}}},"enrichments":{"type":"array","items":{"$ref":"#/components/schemas/Enrichment"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"bulkStatus":{"$ref":"#/components/examples/EnrichBulkStatus"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/enrich/{enrichmentId}":{"get":{"tags":["Enrich"],"summary":"Get the status and result of a single enrichment","operationId":"getEnrichment","x-rate-weight":1,"x-credits":{"price":0},"description":"Poll this endpoint until `status` is `done` or `failed`.\n\n**Cost** Free. The 3-credit charge happened (or didn't, if you had\nprior access) on the originating POST.\n\n**Behavior** Stats, scores, insights and brands are frozen at\ncompletion time — future creator metric updates aren't reflected\nhere. **`email` and `audience` are the exception: they are\nlive-mirrored from your workspace's contact at read time**, so\nasynchronous discovery started by a charged enrichment (email\nwaterfall, engine-generated audience) appears on this endpoint\nonce it lands — keep polling this same URL to collect it. For an\nalways-current view of a creator, use\n`GET /api/v1/creators/{creator_id}` (separate endpoint).\n\n**Ratings & ranks** Once `done`, the profile's ratings and ranks —\n`stats.<platform>.ratings`, `insights.brand_safety_label` and\n`rankings` — are added at read time too (never frozen). The\nenrichment computes its ratings before turning `done`, so the first\n`done` read normally has them; `meta.ratings_status` is `deferred`\nwhen some are still computing. See \"Ratings & ranks\" in the intro.\n\n**Retention** 30 days from the `created_at` on the record. Past\nthat, returns `410 Gone` with a pointer to the long-lived creator\nendpoint.\n","parameters":[{"name":"enrichmentId","in":"path","example":"6701a2b3c4d5e6f7a8b9c0d1","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current status + data if available","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Enrichment"},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"ratings_status":{"$ref":"#/components/schemas/RatingsStatus"}}}]}}},"examples":{"enrichmentDone":{"$ref":"#/components/examples/EnrichmentDone"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/EnrichmentExpired"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/creators/{creatorId}":{"get":{"tags":["Creators"],"summary":"Live read of a creator with an active access window","operationId":"getCreator","x-rate-weight":1,"x-credits":{"price":0},"description":"The long-lived companion to `/enrich`: read the CURRENT data of any\ncreator your workspace unlocked in the last 30 days (charged enrich\nor in-app unlock), using just the `creator_id`. No enrichment id to\nkeep around, no new enrichment record created.\n\n**Cost** Free while the 30-day access window is open. Once it\nexpires this returns `402` — `POST /api/v1/enrich` (3 credits)\nopens a new window.\n\n**Freshness** The payload is built from live data at request time.\nEach call also fires the same free stats refresh the app's Refresh\nbutton runs — in the background (the GET never waits on it) and at\nmost once per hour per creator. `meta.refresh_status` reports where\nthat stands: `triggered` (refresh kicked off — poll again in ~30s\nfor updated stats), `in_progress`, `fresh` (refreshed within the\nlast hour), `deferred` (refresh capacity was momentarily full — a\nlater call will trigger it), or `null` (no workspace contact to\nrefresh). Fields you manually edited in the app are never\noverwritten by this refresh.\n\n**Email & audience** always mirror your workspace's contact.\nDiscovery itself (email waterfall, audience fetch) only runs on\ncharged enrichs — a free read never fires it.\n\n**Ratings & ranks** Every read carries the profile's ratings and\nranks — `stats.<platform>.ratings`, `insights.brand_safety_label`\nand `rankings`. Computed on the read and cached (ratings up to 24\nhours, ranks up to 12); the first read of a creator with several\nplatforms can answer `meta.ratings_status: \"deferred\"` with some\n`ratings: null` — read again a few seconds later. See \"Ratings &\nranks\" in the intro.\n","parameters":[{"name":"creatorId","in":"path","example":"63a477561c819689ff4e32f8","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"The `creator_id` from any enrichment result, list contact or campaign creator (24 hex characters; anything else is a `422`)."}],"responses":{"200":{"description":"Current creator data — same shape as an enrichment result's `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EnrichmentData"},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"refresh_status":{"type":"string","nullable":true,"enum":["triggered","in_progress","fresh","deferred"],"description":"Background-refresh state for this creator's workspace contact."},"ratings_status":{"$ref":"#/components/schemas/RatingsStatus"}}}]}}},"examples":{"creatorRead":{"$ref":"#/components/examples/CreatorRead"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `access_required` — no active access window for this creator in your workspace: `POST /api/v1/enrich` (3 credits) unlocks 30 days of live reads.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"accessRequired":{"summary":"access_required","value":{"error":{"code":"access_required","message":"No active access window for this creator. POST /api/v1/enrich (3 credits) unlocks 30 days of live reads.","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`creator_not_found` — no creator with this id.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"creatorNotFound":{"summary":"creator_not_found","value":{"error":{"code":"creator_not_found","message":"No creator with this id.","status":404,"details":[]}}}}}}},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/lists":{"get":{"tags":["Lists"],"summary":"List the caller's contact lists","operationId":"listLists","x-rate-weight":1,"x-credits":{"price":0},"description":"Page through every contact list owned by the authenticated\nworkspace. Each entry includes an active contact count.\n\n**Cost** Free.\n\n**Freshness** Real-time — every read hits the database.\n","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Paginated list of contact lists.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactList"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"lists":{"$ref":"#/components/examples/ListsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl \"https://listening-api.favikon.com/api/v1/lists?per_page=20\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"}]},"post":{"tags":["Lists"],"summary":"Create a new contact list","operationId":"createList","x-rate-weight":1,"x-credits":{"price":0},"description":"Create a contact list owned by the caller's workspace.\n\n**Cost** Free.\n\n**Behavior** List names must be unique within the workspace.\nOn collision returns `409 list_already_exists` rather than\nsilently aliasing or appending. The response body shape matches\n`GET /lists` items so you can use the same renderer.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100}}},"examples":{"newList":{"summary":"A new list","value":{"name":"Fashion creators — Europe"}},"quickstart":{"summary":"Quickstart: a list for them","value":{"name":"Vegan chefs — Paris"}}}}}},"responses":{"201":{"description":"List created. Body shape matches `GET /lists` items for easy rendering.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContactList"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"listCreated":{"$ref":"#/components/examples/ListCreated"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https://listening-api.favikon.com/api/v1/lists\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Fashion creators — Europe\"}'\n"}]}},"/api/v1/lists/{listId}":{"delete":{"tags":["Lists"],"summary":"Delete a contact list","operationId":"deleteList","x-rate-weight":1,"x-credits":{"price":0},"description":"Hard-delete a list. The contact documents inside it are untouched\n— only the list and its membership array are removed.\n\n**Cost** Free.\n\n**Behavior** 200 with a body matching the bulk single-action\nshape (`list_id`, `name`, `status: \"deleted\"`) — same envelope\nas the campaigns delete endpoints, so consumers can use one\nrenderer for confirmation toasts.\n\nA list a tracker follows (active or paused) can't be deleted:\n`409 list_in_use` names the tracker. Delete the tracker first. A\nsegment's list answers `404`: delete the segment instead.\n","parameters":[{"name":"listId","in":"path","example":"6702a1b2c3d4e5f6a7b8c901","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"List deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"list_id":{"type":"string"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["deleted"]}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"listDeleted":{"$ref":"#/components/examples/ListDeleted"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"`not_found` — no such list in this workspace, or the list belongs to a segment.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"listNotFound":{"$ref":"#/components/examples/ListNotFound"}}}}},"409":{"description":"`list_in_use` — a tracker follows this list (`details[].reason` names it). Delete the tracker, then the list. Nothing was deleted.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"listInUse":{"summary":"list_in_use","value":{"error":{"code":"list_in_use","message":"This list feeds a tracker. Delete the tracker (or switch its source) before deleting the list.","status":409,"details":[{"field":"listId","reason":"used by tracker 6703c1d2e3f4a5b6c7d8e9f0"}]}}}}}}},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X DELETE \"https://listening-api.favikon.com/api/v1/lists/69eb379647b81e79489adc1e\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"}]}},"/api/v1/lists/{listId}/contacts":{"get":{"tags":["Lists"],"summary":"Get the contacts inside a list","operationId":"getListContacts","x-rate-weight":1,"x-credits":{"price":0},"description":"Page through the contacts that belong to a list. Returns a slim\npublic shape per item — id, name, avatar, basic demographics,\nenrichment timestamps. For full CRM fields use\n`GET /campaigns/{campaignId}/creators` (separate endpoint).\n\n**Cost** Free.\n\n**Freshness** Real-time.\n","parameters":[{"name":"listId","in":"path","example":"6702a1b2c3d4e5f6a7b8c901","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Paginated contacts in the list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ListContact"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"contacts":{"$ref":"#/components/examples/ListContactsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl \"https://listening-api.favikon.com/api/v1/lists/69eb379647b81e79489adc1e/contacts?per_page=50\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"}]},"post":{"tags":["Lists"],"summary":"Add one or more creators to a list","operationId":"addListContacts","x-rate-weight":1,"x-credits":{"price":0},"description":"Add 1–100 creators to a list in one request. Two input forms\n(combine freely, max 100 total):\n\n- **`creator_ids`** — Favikon creator ids you already have (e.g.\n  from `POST /enrich`, `GET /lists/{id}/contacts`, or\n  `GET /campaigns/{id}/creators`). Immediate, no engine call.\n- **`handles`** — handles or URLs (same shape as `POST /enrich`).\n  The API resolves each via indexed lookup; unknown creators are\n  ingested from the social network on the fly.\n\nInternally each creator is translated to the customer's Contact\nrow (created if missing, same as the dashboard's \"Add to list\"\nflow) and the Contact id is added to the list.\n\n**Cost** Free. Handle ingestion alone doesn't charge credits;\nonly `POST /enrich` does.\n\n**Behavior** Per-item status: `added`, `already_in_list`,\n`not_found`, `failed`. `already_in_list` is surfaced explicitly\nrather than silently aliasing. Items that fail input parsing or\nnetwork resolution come back with `creator_id: null` plus a\nstructured error. A handle repeated in the request is handled once.\n\n**Fetching unknown handles** is limited (see \"Resolving handles\"):\nnew handles are fetched a few at a time, and none starts after\n**25 seconds** of the request — the rest come back `failed` with\n`ingest_in_progress`: send them again in another request. A `failed`\nitem's `error.code` tells you what to do:\n- `invalid_input` — fix the handle.\n- `ingest_limit_reached` — the workspace has fetched its 500 new\n  creators for today. Retry after midnight UTC.\n- `ingest_in_progress` / `ingest_unavailable` — retry.\n- `workspace_contact_limit_reached` — the workspace's contact limit\n  leaves no room for this creator. Upgrade the plan.\n\n**Contact limit** When the creators new to the workspace don't fit\nits contact limit at all, the call answers\n`403 workspace_contact_limit_reached` before fetching anything.\n\n**Status codes**\n- `201` — every item was newly added\n- `207` — mixed outcomes\n- `409` — every item was already in the list\n- `404` — every item is `not_found`\n- `400` — every item failed\n","parameters":[{"name":"listId","in":"path","example":"6702a1b2c3d4e5f6a7b8c901","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"creator_ids":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"}},"handles":{"type":"array","maxItems":100,"items":{"type":"object","properties":{"linkedinHandle":{"type":"string"},"instagramHandle":{"type":"string"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"xHandle":{"type":"string"}}}}}},"examples":{"byId":{"summary":"Known creator ids","value":{"creator_ids":["6524b53cfa6624efbeeef72a"]}},"byHandle":{"summary":"Handles (ingests if unknown, no credit charge)","value":{"handles":[{"instagramHandle":"bianca.d"},{"linkedinHandle":"marc-richard"}]}},"mixed":{"summary":"Mix of ids and handles","value":{"creator_ids":["6524b53cfa6624efbeeef72a"],"handles":[{"tiktokHandle":"@amauryguichon"}]}},"quickstart":{"summary":"Quickstart: add the top 10","value":{"creator_ids":["656c43ab0c36863cb1ca11c5","62b5e1f0a9c8d7e6f5a4b3c2","61d4c3b2a1f0e9d8c7b6a5f4","63a477561c819689ff4e32f8","6524b53cfa6624efbeeef72a","69bb967146ae23484eb74d66","64a1b2c3d4e5f6a7b8c9d0e1","64a1b2c3d4e5f6a7b8c9d0e2","64a1b2c3d4e5f6a7b8c9d0e3","64a1b2c3d4e5f6a7b8c9d0e4"]}}}}}},"responses":{"201":{"description":"Every contact was newly added to the list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allAdded":{"$ref":"#/components/examples/ListContactsAdded"}}}}},"207":{"description":"Multi-status — some added, some already in the list / not found / failed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"mixed":{"$ref":"#/components/examples/ListContactsMixed"}}}}},"400":{"description":"Every item failed. Body is the same success-shaped envelope as 201/207 (`data.summary` + per-item `contacts[]`), not the error envelope — inspect per-item `status` / `error`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allFailed":{"$ref":"#/components/examples/ListContactsAllFailed"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ContactLimitForbidden"},"404":{"description":"Two shapes share this code — an unknown `listId` returns the standard error envelope, while \"every submitted item was `not_found`\" returns the success-shaped envelope with per-item details (same body as 207).","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ListContactsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}}]},"examples":{"listNotFound":{"$ref":"#/components/examples/ListNotFound"},"allNotFound":{"$ref":"#/components/examples/ListContactsAllNotFound"}}}}},"409":{"description":"Every item was already in the list (idempotent collision — nothing changed). Body is the success-shaped envelope with all items `already_in_list`, not the error envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allAlreadyInList":{"$ref":"#/components/examples/ListContactsAllPresent"}}}}},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/lists/{listId}/contacts/bulk-delete":{"post":{"tags":["Lists"],"summary":"Remove up to 100 contacts from a list in one request","operationId":"bulkDeleteListContacts","x-rate-weight":1,"x-credits":{"price":0},"description":"Bulk-remove contacts from a list. Exists so callers don't fan out\nN parallel `DELETE` calls and trip the rate limit.\n\nThree input forms (combine freely, max 100 total):\n\n- **`creator_ids`** — Favikon creator ids you already have.\n- **`handles`** — handles or URLs. **Lookup-only** here: handles\n  are resolved via the indexed per-network collection, with **no**\n  external data fetch. Unknown handles come back as `not_found`\n  since they obviously aren't in your list.\n- **`contact_ids`** — the `contact_id` from\n  `GET /lists/{listId}/contacts`. The cleanup path for contacts\n  whose `creator_id` is `null` (dead or unresolvable profiles),\n  which the other two forms can never address.\n\n**Cost** Free.\n\n**Behavior** Per-item status: `removed`, `not_in_list`,\n`not_found`, `failed`. `not_in_list` is treated as idempotent\nsuccess — removing a creator who isn't in the list is not an\nerror. The Contact documents themselves are untouched; only the\nlist membership is pulled.\n\n**Status codes**\n- `200` — every item was `removed` or `not_in_list`\n- `207` — mix with `failed` or `not_found`\n- `404` — every item is `not_found`\n- `400` — every item failed\n","parameters":[{"name":"listId","in":"path","example":"6702a1b2c3d4e5f6a7b8c901","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Provide at least one of `creator_ids`, `handles`, or\n`contact_ids` (combined max 100). Handles are resolved via\nindexed lookup only — unknown creators come back as\n`not_found` without an engine call.\n","properties":{"creator_ids":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"}},"handles":{"type":"array","maxItems":100,"items":{"type":"object","properties":{"linkedinHandle":{"type":"string"},"instagramHandle":{"type":"string"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"xHandle":{"type":"string"}}}},"contact_ids":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"Contact ids (from `GET /lists/{listId}/contacts`) — removable even when the contact has no linked creator."}}},"examples":{"byId":{"summary":"Known creator ids","value":{"creator_ids":["6524b53cfa6624efbeeef72a"]}},"byContactId":{"summary":"Cleanup of creator-less contacts by contact id","value":{"contact_ids":["6a57fbd687e16e14f248b2fb"]}},"byHandle":{"summary":"By handle","value":{"handles":[{"instagramHandle":"bianca.d"}]}},"mixed":{"summary":"Mix of ids and handles","value":{"creator_ids":["6524b53cfa6624efbeeef72a"],"handles":[{"tiktokHandle":"@amauryguichon"}]}}}}}},"responses":{"200":{"description":"Every contact was removed or was not in the list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allRemoved":{"$ref":"#/components/examples/ListContactsRemoved"}}}}},"207":{"description":"Multi-status — some removed, some failed or not found.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"mixed":{"$ref":"#/components/examples/ListContactsRemoveMixed"}}}}},"400":{"description":"Every item failed. Body is the same success-shaped envelope as 200/207 (`data.summary` + per-item `contacts[]`), not the error envelope.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListContactsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allFailed":{"$ref":"#/components/examples/ListContactsRemoveAllFailed"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Two shapes share this code — an unknown `listId` returns the standard error envelope, while \"every submitted item was `not_found`\" returns the success-shaped envelope with per-item details (same body as 207).","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ListContactsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}}]},"examples":{"listNotFound":{"$ref":"#/components/examples/ListNotFound"},"allNotFound":{"$ref":"#/components/examples/ListContactsRemoveAllNotFound"}}}}},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/lists/{listId}/contacts/{creatorId}":{"delete":{"tags":["Lists"],"summary":"Remove a single creator from a list","operationId":"removeListContact","x-rate-weight":1,"x-credits":{"price":0},"description":"Remove one creator's contact from a list. The Contact document\nitself is untouched — only its membership in this list is pulled.\n\n**Cost** Free.\n\n**Behavior** Returns `200` with a body matching the bulk-delete\nsingle-item shape. `404` when the list isn't owned by the caller,\nthe creator isn't a contact of this workspace, or the creator\nisn't a member of this specific list — we check membership\nexplicitly so you can't get a misleading `200` for a no-op pull.\n","parameters":[{"name":"listId","in":"path","example":"6702a1b2c3d4e5f6a7b8c901","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"creatorId","in":"path","example":"6524b53cfa6624efbeeef72a","required":true,"description":"GlobalInfluencer id.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"Contact removed from the list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"list_id":{"type":"string"},"creator_id":{"type":"string"},"contact_id":{"type":"string"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["removed"]}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"removed":{"$ref":"#/components/examples/ListContactRemoved"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/campaigns/{campaignId}/analytics":{"get":{"tags":["Campaigns"],"summary":"Get campaign overview analytics","operationId":"getCampaignAnalytics","x-rate-weight":1,"x-credits":{"price":0},"description":"Returns a curated analytics snapshot for a single campaign:\nsummary metrics, cost breakdown, platform-level performance,\ntime-series of daily posts and engagement, and the creator funnel.\n\n**Cost** Free.\n\n**Freshness** Reflects the latest sync — see\n`meta.last_synced_at`. Sync cadence depends on campaign type\n(typically every few hours).\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"currency","in":"query","description":"Override the campaign's display currency (ISO 4217, e.g. USD, EUR)","required":false,"schema":{"type":"string","maxLength":3}}],"responses":{"200":{"description":"Campaign analytics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignAnalytics"},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"last_synced_at":{"type":"string","format":"date-time"}}}]}}},"example":{"data":{"campaign":{"id":"6702b2c3d4e5f6a7b8c9d0e1","title":"Pipelane — Q4 founder series","status":"active","currency":"EUR","start_date":"2026-09-15T09:00:00.000Z","end_date":null,"created_at":"2026-09-12T10:00:00.000Z","url":"https://app.favikon.com/business/campaigns/6702b2c3d4e5f6a7b8c9d0e1/overview"},"summary":{"total_posts":6,"total_creators":3,"total_engagement":5420,"total_views":131800,"total_emv":9480.6},"cost":{"budget":3600,"budget_engaged":3600,"cpm":27.31,"cpe":0.66,"cpv":0.03},"platform_breakdown":{"linkedin":{"posts":4,"engagement":3980,"engagement_rate":4.12,"views":96500,"emv":6940.2,"cpe":0.6,"cpv":0.02,"budget_engaged":2400},"instagram":{"posts":2,"engagement":1440,"engagement_rate":4.08,"views":35300,"emv":2540.4,"cpe":0.83,"cpv":0.03,"budget_engaged":1200}},"time_series":[{"date":"2026-09-22","posts":2,"engagement":1840},{"date":"2026-10-01","posts":4,"engagement":3580}],"creator_funnel":{"activated":3,"replied":3,"accepted":3,"published":3}},"meta":{"api_version":"v1","last_synced_at":"2026-10-05T06:00:00.000Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X GET \\\n  \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/analytics\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"},{"lang":"Python","source":"import requests\n\nresponse = requests.get(\n  \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/analytics\",\n  headers={\"Authorization\": \"Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"}\n)\ndata = response.json()\n"},{"lang":"JavaScript","source":"const response = await fetch(\n  \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/analytics\",\n  { headers: { Authorization: \"Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\" } }\n);\nconst data = await response.json();\n"}]}},"/api/v1/campaigns/{campaignId}/creators":{"get":{"tags":["Campaigns"],"summary":"List campaign creators (CRM view)","operationId":"getCampaignCreators","x-rate-weight":1,"x-credits":{"price":0},"description":"Page through every creator in a campaign with their full CRM\ndata: pipeline status, contact info, socials, demographics,\ncategories, automations, custom properties. Mirrors the\ncampaign-overview table in the dashboard.\n\n**Cost** Free.\n\n**Freshness** Real-time.\n\n**Note** `creator_id` here is a **GlobalInfluencer id** —\nconsistent with `POST /campaigns/{id}/creators` and\n`DELETE /campaigns/{id}/creators/{creatorId}`. The\n`custom_creator_campaign_id` field is the per-campaign pipeline\nrow id; use that to correlate with deliverables/outreach.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["score","status","name","enriched_at","followers","price","post_count"],"default":"score"}},{"name":"sort_order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"status","in":"query","description":"Filter by campaign step status (e.g. new, interested, engaged, validated)","schema":{"type":"string"}},{"name":"automation_status","in":"query","schema":{"type":"string"}},{"name":"platform","in":"query","description":"Filter creators who have posted on this platform","schema":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]}},{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 country code","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"List of campaign creators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Creator"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"creators":{"$ref":"#/components/examples/CampaignCreatorsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/creators?per_page=10&status=activated\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"}]},"post":{"tags":["Campaigns"],"summary":"Add one or more creators to a campaign","operationId":"addCampaignCreators","x-rate-weight":1,"x-credits":{"price":0},"description":"Add 1–100 creators to a campaign in one request. Mirrors the\ndashboard's batch-add pipeline (contacts add → pipeline row\ninsert → AI Inbox thread → activity log) but returns an explicit\nper-item status so clients can tell which items landed.\n\nSingle-creator callers just pass `{ \"creator_ids\": [\"<id>\"] }`\nand read `creators[0].status`. No separate singular endpoint.\n\n**Cost** Free. Adding by handle ingests unknown creators for\nfree; only `POST /enrich` consumes credits. Auto-enrichment of\nthe resulting contact is also free when the customer has valid\nprofile access (same as the dashboard).\n\n**Two input forms** (combine freely, max 100 total):\n- **`creator_ids`** — Favikon creator ids you already have.\n  Immediate, no engine call.\n- **`handles`** — handles or URLs (same shape as `POST /enrich`).\n  Resolved via indexed lookup; unknown creators ingested on the fly.\n\n**Behavior** Per-item status: `added`, `already_in_campaign`,\n`not_found`, `failed`. `already_in_campaign` is surfaced\nexplicitly. Items submitted via `handles` echo `input_handle` on\ntheir result so you can pair input → outcome. A handle repeated in\nthe request is handled once.\n\n**Fetching unknown handles** is limited (see \"Resolving handles\"):\nnew handles are fetched a few at a time, never more than the\ncampaign and the workspace have room for, and none starts after\n**25 seconds** of the request — the rest come back `failed` with\n`ingest_in_progress`: send them again in another request. A `failed`\nitem's `error.code` tells you what to do:\n- `invalid_input` — fix the handle.\n- `ingest_limit_reached` — the workspace has fetched its 500 new\n  creators for today. Retry after midnight UTC.\n- `ingest_in_progress` / `ingest_unavailable` — retry.\n- `workspace_contact_limit_reached` — the workspace's contact limit\n  leaves no room for this creator. Upgrade the plan.\n- `campaign_creator_limit_exceeded` — the campaign has no creator\n  slots left.\n\n**Limits** When the creators to add don't fit the creators-per-campaign\nlimit, the call answers `422 campaign_creator_limit_exceeded`; when\nthe creators new to the workspace don't fit its contact limit at all,\n`403 workspace_contact_limit_reached`. Both are checked before\nanything is fetched, and nothing is added.\n\n**Status codes**\n- `201` — every item was added\n- `207` — mixed outcomes\n- `409` — every item was already in the campaign\n- `404` — every item was a `not_found` creator\n- `400` — every item failed\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCampaignCreatorsInput"},"examples":{"byId":{"summary":"Known creator ids","value":{"creator_ids":["6524b53cfa6624efbeeef72a","69bb967146ae23484eb74d66"],"step_status_slug":"new"}},"byHandle":{"summary":"Handles (will ingest if unknown, no credit charge)","value":{"handles":[{"linkedinHandle":"marc-richard"},{"instagramHandle":"bianca.d"}]}},"mixed":{"summary":"Mix of ids and handles in one request","value":{"creator_ids":["6524b53cfa6624efbeeef72a"],"handles":[{"tiktokHandle":"@amauryguichon"}],"step_status_slug":"new"}}}}}},"responses":{"201":{"description":"All creators successfully added.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignCreatorsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allAdded":{"$ref":"#/components/examples/CampaignCreatorsAdded"}}}}},"207":{"description":"Multi-status — some items succeeded, others are already in the campaign / not found / failed. Inspect the `summary` and per-item `status`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignCreatorsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"mixed":{"$ref":"#/components/examples/CampaignCreatorsMixed"}}}}},"400":{"description":"Every item failed to add. Body carries per-item errors.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignCreatorsMutationResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allFailed":{"$ref":"#/components/examples/CampaignCreatorsAllFailed"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ContactLimitForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema.\n- `campaign_creator_limit_exceeded` — the creators to add don't fit the workspace's creators-per-campaign limit. Nothing was added.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"$ref":"#/components/examples/InvalidParameters"},"campaignCreatorLimitExceeded":{"summary":"campaign_creator_limit_exceeded","value":{"error":{"code":"campaign_creator_limit_exceeded","message":"Adding 30 creator(s) would exceed your 500-creator limit per campaign (currently at 480).","status":422,"details":[{"field":"creator_ids","reason":"limit 500, current 480, requested 30"}]}}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/creators\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"creator_ids\":[\"6524b53cfa6624efbeeef72a\"]}'\n"}]}},"/api/v1/campaigns/{campaignId}/creators/bulk-delete":{"post":{"tags":["Campaigns"],"summary":"Remove up to 100 creators from a campaign in one request","operationId":"bulkDeleteCampaignCreators","x-rate-weight":1,"x-credits":{"price":0},"description":"Bulk-remove creators from a campaign. Exists so callers don't fan\nout N parallel `DELETE` calls and trip the rate limit.\n\n**Cost** Free.\n\n**Behavior** Per-item status: `removed`, `not_in_campaign`,\n`not_found`, `failed`. `not_in_campaign` is treated as idempotent\nsuccess. Each removal runs the full cleanup pipeline (cancel\npending outreach → delete pipeline row → async cleanup of inbox\nthread, messages, deliverables). The creator itself stays\nindexed; only the campaign link is cut.\n\n**Status codes**\n- `200` — every item was `removed` or `not_in_campaign`\n- `207` — mix with `failed` or `not_found`\n- `404` — every item is `not_found`\n- `400` — every item failed\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["creator_ids"],"properties":{"creator_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"}}}},"examples":{"byId":{"summary":"Known creator ids","value":{"creator_ids":["6524b53cfa6624efbeeef72a","69bb967146ae23484eb74d66"]}}}}}},"responses":{"200":{"description":"Every creator was removed (or already not in the campaign).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignCreatorsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allRemoved":{"$ref":"#/components/examples/CampaignCreatorsRemoved"}}}}},"207":{"description":"Multi-status — some removed, some failed or not found.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignCreatorsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"mixed":{"$ref":"#/components/examples/CampaignCreatorsRemoveMixed"}}}}},"400":{"description":"Every item failed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignCreatorsDeleteResult"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"allFailed":{"$ref":"#/components/examples/CampaignCreatorsRemoveAllFailed"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X POST \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/creators/bulk-delete\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"creator_ids\":[\"6524b53cfa6624efbeeef72a\",\"69bb967146ae23484eb74d66\"]}'\n"}]}},"/api/v1/campaigns/{campaignId}/creators/{creatorId}":{"delete":{"tags":["Campaigns"],"summary":"Remove a single creator from a campaign","operationId":"removeCampaignCreator","x-rate-weight":1,"x-credits":{"price":0},"description":"Remove one creator from a campaign. The creator stays indexed in\nFavikon — only their link to this campaign is cut.\n\n**Cost** Free.\n\n**Behavior** Resolves `creatorId` (a GlobalInfluencer id) to the\nper-campaign pipeline row, then runs the same cleanup the\ndashboard uses: cancel pending outreach, delete the pipeline\nrow, then async cleanup of inbox thread, messages, deliverables.\nReturns `200` with a body matching the bulk-delete single-item\nshape so consumers can use one renderer.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"creatorId","in":"path","example":"6524b53cfa6624efbeeef72a","required":true,"description":"GlobalInfluencer id. This is the `creator_id` from `GET /campaigns/{campaignId}/creators`.","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}}],"responses":{"200":{"description":"Creator removed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"campaign_id":{"type":"string"},"creator_id":{"type":"string"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["removed"]},"custom_creator_campaign_id":{"type":"string","nullable":true}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"removed":{"$ref":"#/components/examples/CampaignCreatorRemoved"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}},"x-codeSamples":[{"lang":"cURL","source":"curl -X DELETE \"https://listening-api.favikon.com/api/v1/campaigns/6702b2c3d4e5f6a7b8c9d0e1/creators/6524b53cfa6624efbeeef72a\" \\\n  -H \"Authorization: Bearer fav_xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n"}]}},"/api/v1/campaigns/{campaignId}/creators/analytics":{"get":{"tags":["Campaigns"],"summary":"Per-creator performance metrics","operationId":"getCampaignCreatorsAnalytics","x-rate-weight":1,"x-credits":{"price":0},"description":"Per-creator performance for a campaign — engagement, views, EMV,\nCPM/CPE/CPV, conversion events. Use this when you want\ncreator-level numbers without the full CRM payload from\n`GET /campaigns/{id}/creators`.\n\n**Cost** Free.\n\n**Freshness** Mirrors the campaign sync cadence — check\n`meta.last_synced_at` on `GET /campaigns/{id}/analytics` (this\nendpoint's own `meta` carries pagination only).\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["engagement","views","impressions","reach","emv","posts","engagement_rate"],"default":"engagement"},"description":"`impressions` and `reach` are legacy aliases of `views` (the response's view metric) — all three sort identically."},{"name":"sort_order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Per-creator analytics","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CreatorAnalytics"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"creators":{"$ref":"#/components/examples/CampaignCreatorsAnalyticsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/campaigns/{campaignId}/posts":{"get":{"tags":["Posts"],"summary":"List campaign posts","operationId":"getCampaignPosts","x-rate-weight":1,"x-credits":{"price":0},"description":"Paginated posts tracked in a campaign with their engagement\nmetrics. Supports filtering by platform, creator, date range, and\napproval status.\n\n**Cost** Free.\n\n**Freshness** Mirrors the campaign sync cadence — check\n`meta.last_synced_at` on `GET /campaigns/{id}/analytics` (this\nendpoint's own `meta` carries pagination only).\n\n**Note** Deliverable posts use 4 statuses: `draft`, `approved_by_brand`\n(brand-approved), `pending` (auto-detected), and `approved` (live).\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["views","engagement","likes","comments","shares","engagement_rate","emv","published_at"],"default":"published_at"}},{"name":"sort_order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"platform","in":"query","schema":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]}},{"name":"creator_id","in":"query","description":"Only this creator's posts (a 24-character hex creator id; anything else is a `422`).","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"}},{"name":"published_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"published_before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","description":"Filter by post status. Default: `all` (approved + approved_by_brand + draft + pending).","schema":{"type":"string","enum":["all","approved","draft","pending"],"default":"all"}}],"responses":{"200":{"description":"List of posts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Post"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"posts":{"$ref":"#/components/examples/CampaignPostsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/campaigns/{campaignId}/posts/{postId}":{"get":{"tags":["Posts"],"summary":"Get post detail","operationId":"getCampaignPost","x-rate-weight":1,"x-credits":{"price":0},"description":"Single post with full content, media URL, hashtags, mentions, and\nengagement metrics. Use after `GET /campaigns/{id}/posts` when\nyou need the full caption and media.\n\n**Cost** Free.\n\n**Freshness** Mirrors the campaign sync cadence.\n\n**Media URL** Pre-signed S3 URL valid for 7 days. Re-fetch this\nendpoint for fresh URLs if needed.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"postId","in":"path","example":"6702d4e5f6a7b8c9d0e1f201","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostDetail"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"post":{"$ref":"#/components/examples/CampaignPostDetail"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/lookalikes":{"post":{"tags":["Lookalikes"],"summary":"Find creators similar to seed creators","operationId":"searchLookalikes","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":2,"per":"page","when":"first_fetch"},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nRanks the creators most similar to 1–10 **seeds** (creator ids or\nhandles) and returns them 25 per page, best match first.\n\n**Two ways to call it**\n- **New search** — send `seeds` (and optional `filters`). Returns page\n  1 and, when there are more, `meta.pagination.next_cursor`.\n- **Next page** — send `{ \"cursor\": \"<next_cursor>\" }`. `seeds` and\n  `filters` are ignored: the page comes from the saved search, kept\n  for **1 hour** (then `404 search_expired`).\n\n**Seeds still being analysed** A seed must be analysed before it can\ndrive a search. A creator Favikon hasn't analysed yet — typically one\nyou just passed by handle — is analysed in the background and the call\nanswers **`202 seeds_processing`** with a `Retry-After` header and each\nseed's status. Send the same body again until you get `200` (usually\nunder a minute). A seed that can't be analysed at all (no public bio,\nprivate account, …) returns `422 seeds_unprocessable`: remove it and\nsearch again. Neither costs credits.\n\n**Daily limits** A seed Favikon hasn't analysed yet draws on the\nworkspace's daily budget of **100 seed analyses** (UTC); past it the\ncall answers `429 seed_analysis_limit_reached` until midnight UTC\n(seeds already analysed always work). A seed passed by a handle\nFavikon doesn't know draws on the daily budget of **500 new\ncreators** fetched from the networks (`429 ingest_limit_reached`).\nThe balance is checked first: a workspace that can't pay for page 1\ngets its `402` before anything is fetched or analysed.\n\n**Cost** 2 credits per page returned, charged **once per page** of a\nsearch — requesting the same page again (a retry) is free. A search\nwith no results is free. `meta.credits.cost` is what this call charged.\n\nA free repeat means fetching the same `cursor` again. Sending the same\nbody again starts a new search, charged again.\n\n**Ranking** Up to 1,000 creators per search; a cursor past the last\npage answers `429 search_result_limit`. `match_score` (0–100) is\nthe similarity to your seeds. Seeds are never returned.\n\n**Rate limit** Counts as 5 requests.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"seeds":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/CreatorRef"},"description":"Required for a new search."},"filters":{"$ref":"#/components/schemas/LookalikeFilters"},"cursor":{"type":"string","description":"`meta.pagination.next_cursor` from the previous page. Fetches that page; `seeds` and `filters` are ignored."}}},"examples":{"newSearch":{"summary":"New search","value":{"seeds":["63a477561c819689ff4e32f8",{"instagramHandle":"bianca.d"}],"filters":{"countries":["FR","BE"],"platforms":["instagram"],"platform_stats":{"instagram":{"followers":{"min":10000,"max":500000}}},"hide_saved":true}}},"nextPage":{"summary":"Next page","value":{"cursor":"eyJ2IjoyLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwiaCI6IjZKV194YldVYzVZelpYWXYweGNsckEifQ"}}}}}},"responses":{"200":{"description":"One page of similar creators.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SearchCreator"},{"type":"object","properties":{"match_score":{"type":"integer","minimum":0,"maximum":100,"description":"Similarity to the seeds, 0–100.","example":87}}}]}},"meta":{"$ref":"#/components/schemas/SearchMeta"}}},"examples":{"lookalikePage":{"$ref":"#/components/examples/LookalikePage"}}}}},"202":{"description":"One or more seeds are still being fetched or analysed. Send the same body again after `Retry-After` seconds. No credits charged.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeedsProcessing"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"seedsProcessing":{"$ref":"#/components/examples/SeedsProcessing"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover the page (2 credits), checked before anything runs and again when the page is charged (concurrent calls may have spent the balance meanwhile). Nothing was charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. Each lookalike page costs 2 credits.","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"description":"`search_expired` — the cursor's search is older than 1 hour, or belongs to another workspace. Run the search again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"search_expired","message":"This search has expired (searches are kept for 60 minutes). Run it again.","status":404,"details":[]}}}}},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema (unknown keys included).\n- `invalid_seeds` — some seeds don't resolve to a creator; `details[].field` names each (`seeds[1]`) with the reason in `code` (`not_found`, `private_account`, `account_deleted`, …).\n- `seeds_unprocessable` — some seeds can never drive a search; `details[].reason` is why (`no_bio`, `not_found`, …). `retryable: true` marks a temporary failure worth retrying in ~10 minutes.\n- `invalid_cursor` — `cursor` isn't one this API issued, was edited, or was issued before the current version of the API. Run the search again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidSeeds":{"value":{"error":{"code":"invalid_seeds","message":"Some seeds could not be resolved to a creator.","status":422,"details":[{"field":"seeds[1]","reason":"The instagram account for \"old.handle\" has been deleted.","code":"account_deleted"}]}}},"seedsUnprocessable":{"value":{"error":{"code":"seeds_unprocessable","message":"Some seeds can't be used for a lookalike search. Remove them and search again.","status":422,"details":[{"field":"seeds[0]","reason":"no_bio","retryable":false}]}}},"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Provide at least one seed.","status":422,"details":[{"field":"seeds","reason":"Provide at least one seed."}]}}},"invalidCursor":{"$ref":"#/components/examples/InvalidCursor"}}}}},"429":{"description":"- `rate_limit_exceeded` — more than 20 units in the key's 2-second window. This call counts as **5** (4 per 2 seconds). Wait `Retry-After` seconds.\n- `search_result_limit` — the cursor points past the last page (a search keeps at most 1,000 creators).\n- `ingest_limit_reached` — a seed passed by handle needs fetching from its network, and the workspace has fetched its 500 new creators for today. `details[].field` names each seed; `Retry-After` counts down to midnight UTC. Nothing was charged.\n- `seed_analysis_limit_reached` — some seeds need an analysis, and the workspace has started its 100 seed analyses for today. `details[].field` names each seed; `Retry-After` counts down to midnight UTC. Nothing was charged.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (the key's window, or until midnight UTC for the daily limits)."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimitExceeded":{"$ref":"#/components/examples/SearchRateLimitExceeded"},"searchResultLimit":{"$ref":"#/components/examples/SearchResultLimit"},"ingestLimitReached":{"$ref":"#/components/examples/IngestLimitReached"},"seedAnalysisLimitReached":{"$ref":"#/components/examples/SeedAnalysisLimitReached"}}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/CreatorRefSearchUnavailable"}}}},"/api/v1/radar":{"post":{"tags":["Radar"],"summary":"Find the creators who posted about brands","operationId":"searchRadar","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":2,"per":"page","when":"first_fetch"},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nFinds every creator whose posts mention 1–10 **brands** (creator ids or\nhandles), ranked by `mention_count` — the number of their posts that\nmention the brands — 50 per page, at most **1,000 creators** per\nsearch (the top 1,000 by `mention_count`; `meta.pagination.total`\nis capped at 1,000).\n\n**Two ways to call it**\n- **New search** — send `brands` (and optional `filters`). Returns page\n  1, the `radar_search_id` and, when there are more,\n  `meta.pagination.next_cursor`.\n- **Next page** — send `{ \"cursor\": \"<next_cursor>\" }`. `brands` and\n  `filters` are ignored: the page comes from the saved search, kept for\n  **24 hours** (then `404 radar_search_not_found`).\n\n**Evidence** Pass `radar_search_id` and any returned `creator_id` to\n`GET /api/v1/radar/{radarSearchId}/creators/{creatorId}/posts` to read\nthe posts behind the count — free.\n\n**Coverage** Radar reads mentions on Instagram, TikTok, X and LinkedIn.\n`brands[].tracked_platforms` shows which were scanned for each brand;\na brand with none of them returns `422 brands_not_trackable`.\n\n**Cost** 2 credits per page of 50 creators, charged the first time the\npage is served; fetching the same cursor again is free, and a search\nwith no results is free. Each new search (each POST without a cursor)\nstarts new pages — reuse the cursor. The balance is checked before any\nbrand handle is fetched from its network, and again before each new\npage.\n\n**Daily results quota** Every page's creators count toward the\nworkspace's Discovery results for today, once per page: fetching the\nsame cursor again is not counted again. A page that would go over\nanswers `429 daily_result_limit`, and `meta.usage` shows where the\nworkspace stands. A brand passed by a handle Favikon doesn't know\ndraws on the daily budget of 500 new creators fetched from the\nnetworks (`429 ingest_limit_reached`).\n\n**Rate limit** Counts as 5 requests (cursor pages too).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"brands":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/CreatorRef"},"description":"Required for a new search."},"filters":{"$ref":"#/components/schemas/RadarFilters"},"cursor":{"type":"string","description":"`meta.pagination.next_cursor` from the previous page. Fetches that page; `brands` and `filters` are ignored."}}},"examples":{"newSearch":{"summary":"New search","value":{"brands":[{"instagramHandle":"nike"}],"filters":{"countries":["FR"],"posted_within_days":90,"instagram_post_format":"reel"}}},"nextPage":{"summary":"Next page","value":{"cursor":"eyJ2IjoyLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwiaCI6IjZKV194YldVYzVZelpYWXYweGNsckEifQ"}}}}}},"responses":{"200":{"description":"One page of the creators who mentioned the brands.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RadarSearchResult"},"meta":{"allOf":[{"$ref":"#/components/schemas/SearchMeta"},{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/SearchUsage"}}}]}}},"examples":{"radarSearchPage":{"$ref":"#/components/examples/RadarSearchPage"}}}}},"202":{"description":"A brand passed by handle is still being fetched. Send the same body again after `Retry-After` seconds. No credits charged.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BrandsProcessing"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"brandsProcessing":{"$ref":"#/components/examples/BrandsProcessing"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover the search (2 credits), checked before anything runs and again when page 1 is charged (concurrent calls may have spent the balance meanwhile). Nothing was charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. Each Radar page costs 2 credits.","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"description":"`radar_search_not_found` — the cursor's search is older than 24 hours, or belongs to another workspace. Run the search again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"radarSearchNotFound":{"summary":"radar_search_not_found","value":{"error":{"code":"radar_search_not_found","message":"This Radar search doesn't exist or has expired (searches are kept for 24 hours). Run it again.","status":404,"details":[]}}}}}}},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema (unknown keys included).\n- `invalid_brands` — some brands don't resolve to a creator; `details[].field` names each (`brands[0]`).\n- `brands_not_trackable` — none of the brands has an Instagram, TikTok, X or LinkedIn account. Not charged.\n- `invalid_filters` — the filters could not be applied.\n- `invalid_cursor` — `cursor` isn't one this API issued, was edited, or was issued before the current version of the API. Run the search again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"brandsNotTrackable":{"value":{"error":{"code":"brands_not_trackable","message":"Radar tracks mentions on Instagram, TikTok, X and LinkedIn, and none of these brands has an account there.","status":422,"details":[{"field":"brands","reason":"Tube Brand has no Instagram, TikTok, X or LinkedIn account."}]}}},"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Provide at least one brand.","status":422,"details":[{"field":"brands","reason":"Provide at least one brand."}]}}},"invalidBrands":{"summary":"invalid_brands","value":{"error":{"code":"invalid_brands","message":"Some brands could not be resolved to a creator.","status":422,"details":[{"field":"brands[0]","reason":"The instagram account for \"old.brand\" has been deleted.","code":"account_deleted"}]}}},"invalidFilters":{"summary":"invalid_filters","value":{"error":{"code":"invalid_filters","message":"The filters could not be applied.","status":422,"details":[]}}},"invalidCursor":{"$ref":"#/components/examples/InvalidCursor"}}}}},"429":{"description":"- `rate_limit_exceeded` — more than 20 units in the key's 2-second window. This call counts as **5** (4 per 2 seconds). Wait `Retry-After` seconds.\n- `search_result_limit` — the cursor points past the last page (a search keeps at most 1,000 creators).\n- `daily_result_limit` — the page would take the workspace past its Discovery results for today (UTC); `Retry-After` counts down to midnight UTC. Nothing was charged or counted.\n- `ingest_limit_reached` — a brand passed by handle needs fetching from its network, and the workspace has fetched its 500 new creators for today. `details[].field` names each brand; `Retry-After` counts down to midnight UTC. Nothing was charged.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (the key's window, or until midnight UTC for the daily limits)."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimitExceeded":{"$ref":"#/components/examples/SearchRateLimitExceeded"},"searchResultLimit":{"$ref":"#/components/examples/SearchResultLimit"},"dailyResultLimit":{"$ref":"#/components/examples/DailyResultLimit"},"ingestLimitReached":{"summary":"ingest_limit_reached","value":{"error":{"code":"ingest_limit_reached","message":"This workspace has fetched its daily maximum of new creators from the networks. Creators already in Favikon still work; new ones can be fetched again after midnight UTC.","status":429,"details":[{"field":"brands[0]","reason":"This workspace has fetched 500 new creators from the networks today, the daily maximum. Creators already in Favikon can still be added; new ones can be fetched again after midnight UTC.","code":"ingest_limit_reached"}]}}}}}}},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/CreatorRefSearchUnavailable"}}}},"/api/v1/radar/{radarSearchId}/creators/{creatorId}/posts":{"get":{"tags":["Radar"],"summary":"Posts in which a Radar creator mentions the brands","operationId":"getRadarCreatorPosts","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nThe evidence behind a creator's `mention_count`: their posts that\nmention the brands of a Radar search. **Free** — the creator's page\nwas paid for.\n\nThe brands and filters always come from the saved search (the request\nonly chooses the page and the sort), and only creators on a page of\nthat search you have already fetched can be asked about — fetch the\npage with `POST /radar` first. Searches are kept for 24 hours.\n\n**`mention_count` vs `total`** They usually match; `total` can differ\nslightly because posts are also restricted to the platforms you\nfiltered on, and `posted_within_days` is counted back from now, not\nfrom when the search ran.\n\nAt most 10,000 posts are reachable (`page` × `per_page` ≤ 10,000).\n\n**Cost** Free.\n","parameters":[{"name":"radarSearchId","in":"path","example":"66f3a8ed4b1e2c3d4e5f6a7b","required":true,"description":"`data.radar_search_id` from `POST /api/v1/radar`.","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},{"name":"creatorId","in":"path","example":"62b5e1f0a9c8d7e6f5a4b3c2","required":true,"description":"A `creator_id` from a page of that search you have fetched.","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},{"$ref":"#/components/parameters/Page"},{"name":"per_page","in":"query","description":"Posts per page","schema":{"type":"integer","minimum":1,"maximum":40,"default":20}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["published_at","engagement","likes","comments","shares","views"],"default":"published_at"},"description":"Most recent first by default; the others sort highest first."}],"responses":{"200":{"description":"One page of mention posts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RadarPost"}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"radar_search_id":{"type":"string"},"creator_id":{"type":"string"},"mention_count":{"type":"integer","description":"The creator's `mention_count` in the search."},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}]}}},"examples":{"radarCreatorPosts":{"$ref":"#/components/examples/RadarCreatorPostsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"description":"- `radar_search_not_found` — no such search, older than 24 hours, or another workspace's.\n- `creator_not_in_results` — this creator isn't on a page of that search you have fetched (or isn't in its results at all).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"radarSearchNotFound":{"summary":"radar_search_not_found","value":{"error":{"code":"radar_search_not_found","message":"This Radar search doesn't exist or has expired (searches are kept for 24 hours). Run POST /radar again.","status":404,"details":[]}}},"creatorNotInResults":{"summary":"creator_not_in_results","value":{"error":{"code":"creator_not_in_results","message":"This creator is not on a page of this Radar search that you have fetched.","status":404,"details":[]}}}}}}},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/SearchUnavailable"}}}},"/api/v1/search/creators":{"post":{"tags":["Discovery"],"summary":"Search creators","operationId":"searchCreators","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":1,"per":"25_results","when":"first_fetch"},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nFinds creators matching a natural-language **prompt** (\"vegan chefs in\nParis with a podcast\") and/or **filters** — the app's creator search —\nand returns them as creator cards, `per_page` at a time (1–100,\ndefault 25).\n\n**Two ways to call it**\n- **New search** — send a `prompt` and/or `filters` (and optional\n  `sort`, `per_page`). Returns page 1 and, when there are more,\n  `meta.pagination.next_cursor`.\n- **Next page** — send `{ \"cursor\": \"<next_cursor>\" }`. The rest of the\n  body is ignored: the page comes from the saved search, at its page\n  size, kept for **24 hours**. See \"Pagination\" for the cursor rules.\n\n**Paging** With a prompt (or a metric `sort`), every page is the app's\nsearch \"loading more\": the creators already returned are left out, so\npages never repeat. Fetching the same page again returns it\nunchanged. Without a prompt, the filters are browsed in a random\norder drawn once for the search. Up to 1,000 creators per search;\n`total` is `null` — follow `has_more`.\n\n**Ranking** `relevance` (the default) ranks by match to the prompt and\n`match_score` (0–100) is the match relative to the best result; the\nother sorts rank by a creator metric and `match_score` is `null`.\n\n**Cost** Like the app: 1 credit per 25 of `per_page` (25 → 1,\n100 → 4) for any page with results, charged **once per page** — a\nrepeated page is free. A page with no results is free.\n\nA free repeat means fetching the same `cursor` again. Sending the same\nbody again starts a new search, charged again.\n\n**Quota** Every page counts against the daily results quota.\n\n**Rate limit** Counts as 5 requests.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"prompt":{"type":"string","maxLength":500,"description":"What you're looking for, in plain language.","example":"vegan chefs in Paris"},"sort":{"type":"string","enum":["relevance","authority","followers","growth","engagement","views"],"default":"relevance"},"filters":{"$ref":"#/components/schemas/CreatorSearchFilters"},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Creators per page, fixed for the whole search."},"cursor":{"type":"string","description":"`meta.pagination.next_cursor` from the previous page."}}},"examples":{"newSearch":{"summary":"New search","value":{"prompt":"B2B SaaS founders who post about growth","per_page":50,"filters":{"platforms":["linkedin"],"countries":["FR"],"job_title":"founder","hide_saved":true}}},"nextPage":{"summary":"Next page","value":{"cursor":"eyJ2IjozLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwidyI6IjNmOWExYzBiN2UyZCJ9.l8y8yBU6p7WhA0I2PLQTwA"}},"quickstart":{"summary":"Quickstart: search","value":{"prompt":"vegan chefs in Paris","per_page":25}}}}}},"responses":{"200":{"description":"One page of creators.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CreatorResult"},{"type":"object","properties":{"match_score":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Relevance to the prompt, 0–100; `null` when sorted by a metric or browsing.","example":92}}}]}},"meta":{"$ref":"#/components/schemas/DiscoverySearchMeta"}}},"examples":{"creatorSearchPage":{"$ref":"#/components/examples/CreatorSearchPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover the page (1 credit per 25 of `per_page`). Checked before the search runs, and again when the page is charged: concurrent calls may have spent the balance meanwhile. Nothing was charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. A creator search page costs 1 credit per 25 results of page size (per_page).","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/SearchNotFound"},"410":{"$ref":"#/components/responses/SearchExpired"},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema (unknown keys included).\n- `invalid_cursor` — `cursor` isn't one this API issued, was edited, or was issued before the current version of the API. Run the search again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Number must be less than or equal to 100","status":422,"details":[{"field":"per_page","reason":"Number must be less than or equal to 100"}]}}},"invalidCursor":{"$ref":"#/components/examples/InvalidCursor"}}}}},"429":{"$ref":"#/components/responses/SearchTooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/SearchUnavailableOrBusy"}}}},"/api/v1/search/content":{"post":{"tags":["Discovery"],"summary":"Search content (posts)","operationId":"searchContent","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":1,"per":"page","when":"first_fetch"},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nFinds posts matching **keywords** (minus any `exclude_keywords`) and/or\n`creator_filters` and `post_filters` — the app's content search — and\nreturns them as `PostSummary`, 25 per page, each embedding its\ncreator's card.\n\n**Two ways to call it**\n- **New search** — send `keywords` and/or filters (and optional\n  `exclude_keywords`, `mode`, `operator`, `sort`). Returns page 1 and,\n  when there are more, `meta.pagination.next_cursor`.\n- **Next page** — send `{ \"cursor\": \"<next_cursor>\" }`. The rest of the\n  body is ignored: the page comes from the saved search, kept for **24\n  hours**. See \"Pagination\" for the cursor rules.\n\n**Matching** `hybrid` (the default) mixes meaning and literal words;\n`semantic` matches meaning only; `keyword` matches the words literally\nin captions, hashtags and AI tags (`#tag` matches the hashtag only).\n`operator` joins several keywords. `exclude_keywords` leaves out posts\nmatching any of them — in `keyword` and `hybrid` matching (semantic\nmatching can't exclude). Without keywords the filters are browsed,\nnewest first unless sorted. Unsafe posts are always left out.\n\n**Paging** Posts come grouped by creator, as in the app, and never\nrepeat across pages. `total` is `null` (the search is extended as you\npage); follow `has_more`. Up to 1,000 posts per search.\n\n**Cost** 1 credit per page with results, charged **once per page** — a\nrepeated page is free. A page with no results is free.\n\nA free repeat means fetching the same `cursor` again. Sending the same\nbody again starts a new search, charged again.\n\n**Quota** Every page counts against the daily results quota.\n\n**Rate limit** Counts as 5 requests.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"keywords":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"example":["skincare routine"]},"exclude_keywords":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"Leave out posts matching any of these. Needs `keywords`.","example":["giveaway"]},"mode":{"type":"string","enum":["hybrid","semantic","keyword"],"default":"hybrid"},"operator":{"type":"string","enum":["and","or"],"default":"and"},"sort":{"type":"string","enum":["relevance","recent","views","engagement","engagement_rate","likes","comments","shares"],"default":"relevance"},"creator_filters":{"$ref":"#/components/schemas/ContentCreatorFilters"},"post_filters":{"$ref":"#/components/schemas/PostFilters"},"cursor":{"type":"string","description":"`meta.pagination.next_cursor` from the previous page."}}},"examples":{"newSearch":{"summary":"New search","value":{"keywords":["skincare routine"],"exclude_keywords":["giveaway"],"creator_filters":{"countries":["FR"]},"post_filters":{"platforms":["instagram","tiktok"],"published_after":"2026-06-01","views":{"min":10000}}}},"nextPage":{"summary":"Next page","value":{"cursor":"eyJ2IjozLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwidyI6IjNmOWExYzBiN2UyZCJ9.l8y8yBU6p7WhA0I2PLQTwA"}}}}}},"responses":{"200":{"description":"One page of posts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PostSummary"}},"meta":{"$ref":"#/components/schemas/DiscoverySearchMeta"}}},"examples":{"contentSearchPage":{"$ref":"#/components/examples/ContentSearchPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover the page (1 credit). Checked before the search runs, and again when the page is charged: concurrent calls may have spent the balance meanwhile. Nothing was charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. Each content search page costs 1 credit.","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/SearchNotFound"},"410":{"$ref":"#/components/responses/SearchExpired"},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema (unknown keys included).\n- `invalid_cursor` — `cursor` isn't one this API issued, was edited, was issued before the current version of the API, or skips ahead (only the page after one already served can be fetched). Run the search again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Provide at most 10 keywords.","status":422,"details":[{"field":"keywords","reason":"Provide at most 10 keywords."}]}}},"invalidCursor":{"$ref":"#/components/examples/InvalidCursor"}}}}},"429":{"$ref":"#/components/responses/SearchTooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/SearchUnavailableOrBusy"}}}},"/api/v1/rankings/creators":{"get":{"tags":["Discovery"],"summary":"Creator rankings","operationId":"getCreatorRankings","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":1,"per":"25_rows","when":"every_read","max":8},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nOne page of a favikon.com creator board — the leaderboard, or one\nnarrowed by category, niche, network, location and gender — in the\nboard's order, as creator cards with their `rank`. A board has up to\n200 rows.\n\nThe filters are the slugs favikon.com uses: categories and niches from\n`GET /filters/taxonomy` (`industries[].slug`, `niches[].slug`),\nlocations from `GET /filters/locations` (continent and country slugs,\nand the `groups`). An unknown slug answers `422 invalid_slug`.\n\n**Cost** 1 credit per 25 rows returned, on every read: a page of 50\ncosts 2, an empty page 0, the whole board at most 8. Rows count\ntoward the daily results quota.\n\n**Rate limit** Counts as 5 requests.\n","parameters":[{"$ref":"#/components/parameters/RankingCategory"},{"$ref":"#/components/parameters/RankingNiche"},{"$ref":"#/components/parameters/RankingNetwork"},{"$ref":"#/components/parameters/RankingLocation"},{"name":"gender","in":"query","schema":{"type":"string","enum":["male","female","other"]},"description":"All genders when omitted."},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/RankingPerPage"}],"responses":{"200":{"$ref":"#/components/responses/RankingPage"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover the page (1 credit per 25 rows). Nothing was read or charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. Rankings cost 1 credit per 25 rows returned.","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"422":{"$ref":"#/components/responses/InvalidRankingSlug"},"429":{"description":"- `daily_result_limit` — the page would take the workspace past its Discovery results for today (UTC); `Retry-After` counts down to midnight UTC. Nothing was charged.\n- `rate_limit_exceeded` — more than 20 units per 2 seconds (a rankings read counts as 5).\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (rate limit, daily quota)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"dailyResultLimit":{"$ref":"#/components/examples/DailyResultLimit"},"rateLimitExceeded":{"$ref":"#/components/examples/SearchRateLimitExceeded"}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/rankings/brands":{"get":{"tags":["Discovery"],"summary":"Brand rankings","operationId":"getBrandRankings","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":1,"per":"25_rows","when":"every_read","max":8},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nOne page of a favikon.com brand board, in the board's order, as\ncreator cards (`is_brand: true`) with their `rank`. Same as\n`GET /rankings/creators`, except: categories and niches are the brand\nones (`GET /filters/taxonomy` → `brand_industries`), and there is no\ngender filter.\n\n**Cost** 1 credit per 25 rows returned, on every read. Rows count\ntoward the daily results quota.\n\n**Rate limit** Counts as 5 requests.\n","parameters":[{"$ref":"#/components/parameters/RankingCategory"},{"$ref":"#/components/parameters/RankingNiche"},{"$ref":"#/components/parameters/RankingNetwork"},{"$ref":"#/components/parameters/RankingLocation"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/RankingPerPage"}],"responses":{"200":{"$ref":"#/components/responses/RankingPage"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover the page (1 credit per 25 rows). Nothing was read or charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. Rankings cost 1 credit per 25 rows returned.","status":402,"details":[]}}}}}}},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"422":{"$ref":"#/components/responses/InvalidRankingSlug"},"429":{"description":"- `daily_result_limit` — the page would take the workspace past its Discovery results for today (UTC); `Retry-After` counts down to midnight UTC. Nothing was charged.\n- `rate_limit_exceeded` — more than 20 units per 2 seconds (a rankings read counts as 5).\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (rate limit, daily quota)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"dailyResultLimit":{"$ref":"#/components/examples/DailyResultLimit"},"rateLimitExceeded":{"$ref":"#/components/examples/SearchRateLimitExceeded"}}}}},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/filters/taxonomy":{"get":{"tags":["Discovery"],"summary":"Industries and niches","operationId":"getTaxonomyFilters","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nThe Favikon taxonomy. Searches take the ids (`filters.industry`,\n`filters.niches`); creator rankings take the slugs. `brand_industries`\nare the categories brand rankings take (by slug).\n\n**Cost** Free, and filter lists don't count toward the daily results quota.\n","responses":{"200":{"description":"The taxonomy.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"industries":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyIndustry"}},"brand_industries":{"type":"array","items":{"$ref":"#/components/schemas/TaxonomyIndustry"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"taxonomy":{"$ref":"#/components/examples/TaxonomyFilters"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/filters/locations":{"get":{"tags":["Discovery"],"summary":"Countries, locations and languages","operationId":"getLocationFilters","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nCountries grouped by continent, the location groups rankings also\naccept (worldwide-<language>, Quebec), and the creator languages.\nSearches take the codes — `filters.countries` (ISO 3166-1 alpha-2) and\n`filters.languages` (ISO 639-1, Hebrew as `iw`); rankings take the\nslugs (`location`).\n\n**Cost** Free, and filter lists don't count toward the daily results quota.\n","responses":{"200":{"description":"Countries, groups and languages.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"continents":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"eu"},"slug":{"type":"string","example":"europe"},"name":{"type":"string","example":"Europe"},"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"FR"},"slug":{"type":"string","example":"france"},"name":{"type":"string","example":"France"}}}}}}},"groups":{"type":"array","description":"Rankings-only locations.","items":{"type":"object","properties":{"slug":{"type":"string","example":"worldwide-english"},"name":{"type":"string","example":"English speaking"}}}},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"fr"},"name":{"type":"string","example":"French"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"locations":{"$ref":"#/components/examples/LocationFilters"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/filters/options":{"get":{"tags":["Discovery"],"summary":"Filter options and limits","operationId":"getOptionFilters","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nEvery enum and limit the Discovery requests accept (platforms,\ngenders, profile types, tiers, sorts, modes, content types, metrics,\npage sizes…), and this workspace's daily results quota. Built from the\nrequest validators, so it's always exactly what is accepted.\n\n**Cost** Free, and filter lists don't count toward the daily results quota.\n","responses":{"200":{"description":"Options and limits.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"platforms":{"$ref":"#/components/schemas/StringList"},"genders":{"$ref":"#/components/schemas/StringList"},"profile_types":{"$ref":"#/components/schemas/StringList"},"tiers":{"type":"array","items":{"type":"integer"}},"platform_stats_metrics":{"$ref":"#/components/schemas/StringList"},"creator_search":{"type":"object","properties":{"sorts":{"$ref":"#/components/schemas/StringList"},"default_per_page":{"type":"integer","example":25},"max_per_page":{"type":"integer","example":100}}},"content_search":{"type":"object","properties":{"sorts":{"$ref":"#/components/schemas/StringList"},"modes":{"$ref":"#/components/schemas/StringList"},"operators":{"$ref":"#/components/schemas/StringList"},"content_types":{"$ref":"#/components/schemas/StringList"},"metrics":{"$ref":"#/components/schemas/StringList"},"max_keywords":{"type":"integer","example":10},"max_exclude_keywords":{"type":"integer","example":10},"page_size":{"type":"integer","example":25}}},"rankings":{"type":"object","properties":{"networks":{"$ref":"#/components/schemas/StringList"},"genders":{"$ref":"#/components/schemas/StringList"},"default_per_page":{"type":"integer","example":25},"max_per_page":{"type":"integer","example":100},"max_rows":{"type":"integer","example":200}}},"limits":{"type":"object","properties":{"max_results_per_search":{"type":"integer","example":1000},"search_ttl_hours":{"type":"integer","example":24},"daily_results":{"type":"integer","description":"This workspace's Discovery results per UTC day.","example":10000}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"options":{"$ref":"#/components/examples/OptionFilters"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/segments":{"get":{"tags":["Segments"],"summary":"List segments","operationId":"listSegments","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nThe workspace's segments — drafts, active and paused — newest first.\n\n**Cost** Free.\n","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"One page of segments.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"segments":{"$ref":"#/components/examples/SegmentsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Segments"],"summary":"Create a segment with its rule","operationId":"createSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nCreates a **draft** segment and its rule in one call. Nothing is\ncharged and no member is fetched until `POST /segments/{id}/commit`.\n\nThe rule reuses the body of the matching search endpoint, so a search\nyou already run can be saved as is — see `SegmentRule`.\n\n**Creators by handle** `seeds` (lookalikes), `brands` (Radar) and\n`exclusions.creators` take creator ids or handles. While a handle is\nstill being fetched — or a lookalike seed analysed — the call answers\n**`202`** with a `Retry-After` header and nothing is created: send the\nsame request again. Fetching unknown handles and analysing new seeds\ndraw on the workspace's daily limits (500 new creators, 100 seed\nanalyses — see \"Resolving handles\"): past them the call answers\n`429 ingest_limit_reached` / `429 seed_analysis_limit_reached` until\nmidnight UTC, and `503 ingest_unavailable` when creator lookup is\nbriefly down. `PATCH` follows the same rules.\n\n**Cost** Free.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","rule"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Also the name of the segment's list."},"rule":{"$ref":"#/components/schemas/SegmentRule"},"exclusions":{"$ref":"#/components/schemas/SegmentExclusions"}}},"examples":{"creatorSearch":{"summary":"Creator search","value":{"name":"FR running creators","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"]}}},"lookalikes":{"summary":"Lookalikes","value":{"name":"Like our ambassadors","rule":{"source":"lookalikes","seeds":["63a477561c819689ff4e32f8",{"instagramHandle":"bianca.d"}]}}}}}}},"responses":{"201":{"description":"The draft segment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"draft":{"$ref":"#/components/examples/SegmentDraft"}}}}},"202":{"description":"`seeds_processing` / `brands_processing` / `creators_processing` — some creators are still being fetched or analysed. Nothing was created; send the same request after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SegmentInputsProcessing"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"seedsProcessing":{"$ref":"#/components/examples/SegmentSeedsProcessing"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema, an unknown ranking slug, or an excluded list that isn't in this workspace; `details[].field` names it.\n- `invalid_seeds` / `invalid_brands` / `invalid_exclusions` — some creators can't be resolved (`details[].field`, e.g. `rule.seeds[1]`).\n- `seeds_unprocessable` — some lookalike seeds can't be analysed (no public bio, private account…).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"`source` must be one of creator_search, content_search, lookalikes, radar, rankings.","status":422,"details":[{"field":"rule.source","reason":"`source` must be one of creator_search, content_search, lookalikes, radar, rankings."}]}}},"invalidExclusions":{"summary":"invalid_exclusions","value":{"error":{"code":"invalid_exclusions","message":"Some creators could not be resolved.","status":422,"details":[{"field":"exclusions.creators[0]","reason":"The instagram account for \"old.handle\" has been deleted.","code":"account_deleted"}]}}}}}}},"429":{"$ref":"#/components/responses/SegmentInputsTooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/SegmentInputsUnavailable"}}}},"/api/v1/segments/{segmentId}":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"get":{"tags":["Segments"],"summary":"Get a segment","operationId":"getSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\n**Cost** Free.\n","responses":{"200":{"description":"The segment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"segment":{"$ref":"#/components/examples/SegmentActive"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["Segments"],"summary":"Rename a segment, or change a draft's rule","operationId":"updateSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\n`name` can change at any time (the segment's list is renamed too).\n`rule` and `exclusions` can only change on a **draft** — once\ncommitted, the price and the members are fixed: `409\nsegment_committed`. Each of them replaces the whole stored object.\n\n**Cost** Free.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"rule":{"$ref":"#/components/schemas/SegmentRule"},"exclusions":{"$ref":"#/components/schemas/SegmentExclusions"}}},"examples":{"rename":{"summary":"Rename","value":{"name":"FR running creators — 2026"}},"newRule":{"summary":"Change a draft's rule","value":{"rule":{"source":"creator_search","prompt":"ultra trail runners","filters":{"countries":["FR"]}}}}}}}},"responses":{"200":{"description":"The updated segment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"segment":{"$ref":"#/components/examples/SegmentDraft"}}}}},"202":{"description":"Some creators are still being fetched — see `POST /segments`. Nothing was changed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SegmentInputsProcessing"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"seedsProcessing":{"$ref":"#/components/examples/SegmentSeedsProcessing"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SegmentStateConflict"},"422":{"description":"- `invalid_parameters` — the body doesn't match the schema, an unknown ranking slug, or an excluded list that isn't in this workspace; `details[].field` names it.\n- `invalid_seeds` / `invalid_brands` / `invalid_exclusions` — some creators can't be resolved (`details[].field`, e.g. `rule.seeds[1]`).\n- `seeds_unprocessable` — some lookalike seeds can't be analysed (no public bio, private account…).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"`source` must be one of creator_search, content_search, lookalikes, radar, rankings.","status":422,"details":[{"field":"rule.source","reason":"`source` must be one of creator_search, content_search, lookalikes, radar, rankings."}]}}},"invalidExclusions":{"summary":"invalid_exclusions","value":{"error":{"code":"invalid_exclusions","message":"Some creators could not be resolved.","status":422,"details":[{"field":"exclusions.creators[0]","reason":"The instagram account for \"old.handle\" has been deleted.","code":"account_deleted"}]}}}}}}},"429":{"$ref":"#/components/responses/SegmentInputsTooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/SegmentInputsUnavailable"}}},"delete":{"tags":["Segments"],"summary":"Delete a segment and its list","operationId":"deleteSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\n**Deleting a segment also deletes its list** (`list_id`). The\ncreators stay in your CRM. Trackers created from the segment are\npaused: they keep the creators they track, and can be resumed. Stops\nthe 30-day renewal.\n\n**Cost** Free.\n","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SegmentDeleted"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"deleted":{"$ref":"#/components/examples/SegmentDeleted"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/segments/{segmentId}/count":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"post":{"tags":["Segments"],"summary":"Count a segment and quote its price","operationId":"countSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nHow many creators the segment's **stored** rule matches now, and what\ncommitting it costs at `size_limit` creators (default: every match,\nup to 1000) — the exact figure `POST /commit` expects as\n`confirm_cost`. The same price is charged again every 30 days.\n\nOn a committed segment the commit is a no-op (`commit_cost: 0`) and\n`recurring_cost` is the price fixed at commit.\n\n**Cost** Free. **Rate limit** Counts as 5 requests.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"size_limit":{"type":"integer","minimum":1,"maximum":1000,"description":"Price a commit of this many creators."}}},"examples":{"sizeLimit":{"summary":"Price 200 creators","value":{"size_limit":200}}}}}},"responses":{"200":{"description":"The size and the price.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SegmentCount"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"count":{"$ref":"#/components/examples/SegmentCount"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SegmentStateConflict"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/SearchRateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/segments/{segmentId}/commit":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"post":{"tags":["Segments"],"summary":"Commit a segment","operationId":"commitSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":1,"per":"25_creators","per_brand_or_seed":2,"when":"commit"},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nCharges `confirm_cost` credits, fetches up to `size_limit` members and\ncreates the segment's list. **Waits for the list**, so `list_id` is in\nthe answer and the segment can be tracked right away\n(`POST /trackers` with `segment_id`).\n\n- `confirm_cost` must be the price `POST /count` quotes for this\n  `size_limit`; otherwise **`409 cost_mismatch`** (with the real\n  price in `details[].expected`) and **nothing is charged**.\n- **Committing twice charges once**: a committed segment answers `200`\n  with `meta.already_committed: true` and `meta.credits.cost: 0`,\n  whatever the body. Retrying after an error is safe.\n- **The rule changed meanwhile**: if the segment's rule is replaced\n  (`PATCH`) while the commit runs, the commit is undone and answers\n  `409 cost_mismatch` — **nothing is charged**. Count it again.\n- **Concurrent calls**: the credits are taken all at once before the\n  segment is committed, so when other calls spend the balance at the\n  same time this one can answer `402 insufficient_credits`, even\n  after a successful count. Nothing is charged.\n- The same price is charged again every 30 days, to this workspace,\n  while the segment is active (`next_charge_at`). A renewal the\n  workspace can't pay pauses the segment, and the trackers that\n  follow it.\n- **Exclusions are frozen** at commit and at each paid renewal: the\n  members of the excluded lists (`exclusions.list_ids`) and the\n  disqualified creators (`exclude_disqualified`) at that moment apply\n  until the next renewal. Creators added to an excluded list, or\n  disqualified, in between are left out from the next renewal on.\n\n**Cost** `confirm_cost`. **Rate limit** Counts as 5 requests.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["size_limit","confirm_cost"],"properties":{"size_limit":{"type":"integer","minimum":1,"maximum":1000},"confirm_cost":{"type":"integer","minimum":0,"description":"The price `POST /count` quoted for this `size_limit`."}}},"examples":{"commit200":{"summary":"Commit 200 creators at the quoted price","value":{"size_limit":200,"confirm_cost":8}}}}}},"responses":{"200":{"description":"The committed segment (with `list_id`).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"already_committed":{"type":"boolean","description":"true when the segment was already committed (nothing charged)."}}}]}}},"examples":{"committed":{"$ref":"#/components/examples/SegmentCommitted"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the workspace can't cover `confirm_cost`, including when concurrent calls spent the balance while this commit ran. Nothing was charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits: this commit costs 8 credits.","status":402,"details":[{"field":"credits","reason":"insufficient_credits","required":8}]}}}}}}},"403":{"description":"- `plan_upgrade_required` — not available on the Free plan.\n- `api_discovery_disabled` — the workspace doesn't have the Discovery add-on.\n- `api_access_disabled` — the workspace doesn't have the API add-on.\n- `user_banned` — the key's owner is suspended.\n- `account_pending_deletion` — the key's owner is scheduled for deletion.\n- `key_owner_not_member` — the key's owner is no longer an active member of its workspace (the key was revoked).\n- `key_owner_not_admin` — the key's owner is no longer an owner or admin of its workspace (the key was revoked).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"planUpgradeRequired":{"summary":"plan_upgrade_required","value":{"error":{"code":"plan_upgrade_required","message":"Committing a segment is not available on the Free plan.","status":403,"details":[]}}},"apiDiscoveryDisabled":{"$ref":"#/components/examples/ApiDiscoveryDisabled"},"apiAccessDisabled":{"$ref":"#/components/examples/ApiAccessDisabled"},"userBanned":{"$ref":"#/components/examples/UserBanned"},"accountPendingDeletion":{"$ref":"#/components/examples/AccountPendingDeletion"},"keyOwnerNotMember":{"$ref":"#/components/examples/KeyOwnerNotMember"},"keyOwnerNotAdmin":{"$ref":"#/components/examples/KeyOwnerNotAdmin"}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/CostMismatch"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/SearchRateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/segments/{segmentId}/pause":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"post":{"tags":["Segments"],"summary":"Pause a segment","operationId":"pauseSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nStops the daily refresh and the 30-day renewal charge. The members\nand the list stay as they are. Idempotent. A draft answers `409\nsegment_not_committed`.\n\n**Cost** Free.\n","responses":{"200":{"description":"The paused segment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"paused":{"$ref":"#/components/examples/SegmentPaused"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SegmentStateConflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/segments/{segmentId}/resume":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"post":{"tags":["Segments"],"summary":"Resume a segment","operationId":"resumeSegment","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":1,"per":"25_creators","per_brand_or_seed":2,"when":"lapsed_period"},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nFree while the paid 30-day period still runs (`next_charge_at` in the\nfuture). Once it has lapsed — or after a renewal bounced\n(`charge_failed_at`) — the renewal price is charged again and a new\n30-day period starts (`meta.credits.cost`). A paid resume freezes the\nexclusions again (the excluded lists' members and the disqualified\ncreators as they are now), like a renewal. Idempotent on an active segment.\n\n**Cost** 0, or the renewal price (see above).\n","responses":{"200":{"description":"The active segment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"resumed":{"$ref":"#/components/examples/SegmentResumed"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"- `insufficient_credits` — the renewal can't be paid (`details[].required`). The segment stays paused.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits: resuming costs 8 credits.","status":402,"details":[{"field":"credits","reason":"insufficient_credits","required":8}]}}}}}}},"403":{"description":"- `plan_upgrade_required` — not available on the Free plan.\n- `api_discovery_disabled` — the workspace doesn't have the Discovery add-on.\n- `api_access_disabled` — the workspace doesn't have the API add-on.\n- `user_banned` — the key's owner is suspended.\n- `account_pending_deletion` — the key's owner is scheduled for deletion.\n- `key_owner_not_member` — the key's owner is no longer an active member of its workspace (the key was revoked).\n- `key_owner_not_admin` — the key's owner is no longer an owner or admin of its workspace (the key was revoked).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"planUpgradeRequired":{"summary":"plan_upgrade_required","value":{"error":{"code":"plan_upgrade_required","message":"Resuming a segment is not available on the Free plan.","status":403,"details":[]}}},"apiDiscoveryDisabled":{"$ref":"#/components/examples/ApiDiscoveryDisabled"},"apiAccessDisabled":{"$ref":"#/components/examples/ApiAccessDisabled"},"userBanned":{"$ref":"#/components/examples/UserBanned"},"accountPendingDeletion":{"$ref":"#/components/examples/AccountPendingDeletion"},"keyOwnerNotMember":{"$ref":"#/components/examples/KeyOwnerNotMember"},"keyOwnerNotAdmin":{"$ref":"#/components/examples/KeyOwnerNotAdmin"}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SegmentStateConflict"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/segments/{segmentId}/creators":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"get":{"tags":["Segments"],"summary":"List a segment's members","operationId":"getSegmentCreators","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nThe committed segment's members — its list, as the app shows it — as\ncreator cards. A draft answers `409 segment_not_committed`.\n\n**Cost** Free.\n","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"One page of members.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CreatorCard"}},"meta":{"$ref":"#/components/schemas/PaginatedMeta"}}},"examples":{"creators":{"$ref":"#/components/examples/SegmentCreatorsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SegmentStateConflict"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/trackers":{"get":{"tags":["Trackers"],"summary":"List trackers and the monthly quota","operationId":"listTrackers","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nThe workspace's trackers (active and paused), newest first, and the\nmonthly tracked-creator quota in `meta.quota`.\n\n**Cost** Free.\n","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"One page of trackers.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tracker"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PaginatedMeta"},{"type":"object","properties":{"quota":{"$ref":"#/components/schemas/TrackerQuota"}}}]}}},"examples":{"trackers":{"$ref":"#/components/examples/TrackersPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"tags":["Trackers"],"summary":"Track a list or a segment","operationId":"createTracker","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nTracks the active creators of a list (`list_id`) or of a committed\nsegment (`segment_id`, via its list) — exactly one of the two.\n\nEach creator not already tracked this month takes a quota spot (see\n`GET /trackers`); when they don't all fit: **`409\ntracker_limit_reached`**, nothing created.\n\n**Cost** No credits.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"list_id":{"type":"string"},"segment_id":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":120,"description":"Defaults to the list's name."},"rank_enabled":{"type":"boolean","default":false,"description":"Order the leaderboard by authority by default."}}},"examples":{"fromSegment":{"summary":"Track a committed segment","value":{"segment_id":"66f3a8ed4b1e2c3d4e5f6a7b","name":"Running creators — weekly"}},"fromList":{"summary":"Track a list","value":{"list_id":"6702a1b2c3d4e5f6a7b8c901","name":"Fashion creators — Europe"}},"quickstart":{"summary":"Quickstart: track the list","value":{"list_id":"6702a1b2c3d4e5f6a7b8c901","name":"Vegan chefs — weekly"}}}}}},"responses":{"201":{"description":"The tracker, and the quota after it.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tracker"},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"quota":{"$ref":"#/components/schemas/TrackerQuota"}}}]}}},"examples":{"created":{"$ref":"#/components/examples/TrackerCreated"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/TrackerLimitReached"},"422":{"description":"- `invalid_parameters` — not exactly one of `list_id` / `segment_id`, or the body doesn't match the schema.\n- `list_empty` — the list has no active creators.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Provide exactly one of `list_id` or `segment_id`.","status":422,"details":[{"field":"list_id","reason":"Provide exactly one of `list_id` or `segment_id`."}]}}},"listEmpty":{"summary":"list_empty","value":{"error":{"code":"list_empty","message":"The list has no active creators to track.","status":422,"details":[{"field":"list_id","reason":"list_empty"}]}}}}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/trackers/{trackerId}":{"parameters":[{"$ref":"#/components/parameters/TrackerId"}],"get":{"tags":["Trackers"],"summary":"Get a tracker","operationId":"getTracker","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\n**Cost** Free.\n","responses":{"200":{"description":"The tracker.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tracker"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"tracker":{"$ref":"#/components/examples/Tracker"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"patch":{"tags":["Trackers"],"summary":"Rename a tracker or change its ranking","operationId":"updateTracker","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nA paused tracker answers `409 tracker_paused`: resume it first.\n\n**Cost** Free.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"rank_enabled":{"type":"boolean"}}},"examples":{"rename":{"summary":"Rename","value":{"name":"Running creators — monthly"}},"rankOff":{"summary":"Turn ranking off","value":{"rank_enabled":false}}}}}},"responses":{"200":{"description":"The updated tracker.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tracker"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"tracker":{"$ref":"#/components/examples/Tracker"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/TrackerPaused"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"tags":["Trackers"],"summary":"Delete a tracker","operationId":"deleteTracker","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nIts creators keep their quota spots until the monthly reset. Its list\n(or segment) is not touched.\n\n**Cost** Free.\n","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["deleted"]}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"deleted":{"$ref":"#/components/examples/TrackerDeleted"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/InvalidParameters"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/trackers/{trackerId}/pause":{"parameters":[{"$ref":"#/components/parameters/TrackerId"}],"post":{"tags":["Trackers"],"summary":"Pause a tracker","operationId":"pauseTracker","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nNo more nightly updates or digests. Its creators keep their quota\nspots. A paused tracker stays readable: its leaderboard and posts end\nat its last update. Idempotent.\n\n**Cost** Free.\n","responses":{"200":{"description":"The paused tracker.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tracker"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"paused":{"$ref":"#/components/examples/TrackerPaused"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/trackers/{trackerId}/resume":{"parameters":[{"$ref":"#/components/parameters/TrackerId"}],"post":{"tags":["Trackers"],"summary":"Resume a tracker","operationId":"resumeTracker","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":1,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nFree — a paused tracker never released its quota spots. Idempotent.\n\n**Refresh** A tracker whose data is more than 10 days old (or was\nnever computed) is refreshed right away; otherwise it keeps its\nregular schedule — pausing and resuming doesn't force a refresh.\n\n**Cost** Free.\n","responses":{"200":{"description":"The active tracker.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tracker"},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"resumed":{"$ref":"#/components/examples/Tracker"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"- `plan_upgrade_required` — not available on the Free plan.\n- `api_discovery_disabled` — the workspace doesn't have the Discovery add-on.\n- `api_access_disabled` — the workspace doesn't have the API add-on.\n- `user_banned` — the key's owner is suspended.\n- `account_pending_deletion` — the key's owner is scheduled for deletion.\n- `key_owner_not_member` — the key's owner is no longer an active member of its workspace (the key was revoked).\n- `key_owner_not_admin` — the key's owner is no longer an owner or admin of its workspace (the key was revoked).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"planUpgradeRequired":{"summary":"plan_upgrade_required","value":{"error":{"code":"plan_upgrade_required","message":"Resuming a tracker is not available on the Free plan.","status":403,"details":[]}}},"apiDiscoveryDisabled":{"$ref":"#/components/examples/ApiDiscoveryDisabled"},"apiAccessDisabled":{"$ref":"#/components/examples/ApiAccessDisabled"},"userBanned":{"$ref":"#/components/examples/UserBanned"},"accountPendingDeletion":{"$ref":"#/components/examples/AccountPendingDeletion"},"keyOwnerNotMember":{"$ref":"#/components/examples/KeyOwnerNotMember"},"keyOwnerNotAdmin":{"$ref":"#/components/examples/KeyOwnerNotAdmin"}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/trackers/{trackerId}/creators":{"parameters":[{"$ref":"#/components/parameters/TrackerId"}],"get":{"tags":["Trackers"],"summary":"Tracker leaderboard","operationId":"getTrackerCreators","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nEach tracked creator's card, `rank` and numbers over the period —\nthe app's creators tab, computed by the same service. `meta.total` is\nthe number of creators matching `network` + `search`.\n\n**Order** `sort` + `order`; without `sort`, authority (ranked\ntrackers) or the list's order. `rank` is the position in that order\nover the whole tracker — a creator found by `search` keeps it.\n\n**Period** `period`, or `start_date` + `end_date` (a bare date covers\nits whole UTC day). A paused tracker reads the period ending at its\nlast update.\n\n**Cost** Free. **Rate limit** Counts as 5 requests.\n","parameters":[{"$ref":"#/components/parameters/TrackerPeriod"},{"$ref":"#/components/parameters/TrackerStartDate"},{"$ref":"#/components/parameters/TrackerEndDate"},{"name":"network","in":"query","schema":{"type":"string","enum":["all","instagram","tiktok","youtube","linkedin","x"],"default":"all"},"description":"Only creators present on this network, with this network's numbers."},{"name":"search","in":"query","schema":{"type":"string","maxLength":100},"description":"Case-insensitive match on the creator's name or title."},{"name":"sort","in":"query","schema":{"type":"string","enum":["name","authority","followers","growth","followers_evolution","posts","engagement","engagement_count","views","likes","comments","shares"]},"description":"`engagement` is the engagement rate; `engagement_count` the total engagements."},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"One page of the leaderboard.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrackerCreatorRow"}},"meta":{"allOf":[{"$ref":"#/components/schemas/PaginatedMeta"},{"type":"object","properties":{"start_date":{"type":"string","format":"date-time"},"end_date":{"type":"string","format":"date-time"},"network":{"type":"string"},"tracker_creator_count":{"type":"integer","description":"Creators in the tracker, before `network` and `search`."}}}]}}},"examples":{"leaderboard":{"$ref":"#/components/examples/TrackerCreatorsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"`invalid_parameters` — the query doesn't match the schema, or the custom period is out of bounds (start in the future or more than 730 days ago, longer than 366 days, start after end). `details[].field` names the parameter.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"$ref":"#/components/examples/InvalidParameters"},"windowTooLong":{"summary":"invalid_parameters (custom period)","value":{"error":{"code":"invalid_parameters","message":"A custom window spans at most 366 days.","status":422,"details":[{"field":"end_date","reason":"A custom window spans at most 366 days."}]}}}}}}},"429":{"$ref":"#/components/responses/SearchRateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/trackers/{trackerId}/posts":{"parameters":[{"$ref":"#/components/parameters/TrackerId"}],"get":{"tags":["Trackers"],"summary":"Tracker posts feed","operationId":"getTrackerPosts","x-badges":[{"name":"Discovery add-on"}],"x-rate-weight":5,"x-credits":{"price":0},"description":"> [!IMPORTANT]\n> **Requires the Discovery add-on**, turned on for the workspace by your\n> Favikon contact. Without it this call answers `403 api_discovery_disabled`.\n\nEvery post of the tracker's creators over the period, filtered and\nsorted in Elasticsearch over the whole feed — the order is correct\nacross all pages, even past 10,000 posts.\n\n**Two ways to call it**\n- **First call** — send the period, filters, `sort` and `per_page`.\n  Returns the first page, `meta.pagination.total` and\n  `meta.pagination.next_cursor`.\n- **Next pages** — send **only** `?cursor=<next_cursor>`. The filters,\n  the period (resolved to fixed dates) and the sort are locked in the\n  feed; sending anything else with a cursor is a `422`. To change\n  them, start over without a cursor. `next_cursor` is `null` on the\n  last page.\n\n**Consistent to the end** The feed is a snapshot taken at the first\ncall: posts that arrive (or whose numbers change) while you page\nnever shift, repeat or skip a page, and replaying a cursor returns\nthe same page. A cursor stays valid **10 minutes** after the call\nthat returned it — a feed idle longer answers `410 search_expired`.\nThe last page closes the feed: replaying its cursor answers `410`\ntoo. A workspace keeps at most **10 feeds** open; starting an 11th\ncloses the one paged least recently (its next cursor answers `410\nsearch_expired`).\n\n**Filters** Each is a list (comma-separated or repeated); a post must\nmatch **every** filter that is set, and **any** value within one.\n`creator_ids` outside the tracker select nobody.\n\nNo page cache: every page is read live.\n\n**Cost** Free. **Rate limit** Counts as 5 requests.\n","parameters":[{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`meta.pagination.next_cursor` of the previous page. Send it alone."},{"$ref":"#/components/parameters/TrackerPeriod"},{"$ref":"#/components/parameters/TrackerStartDate"},{"$ref":"#/components/parameters/TrackerEndDate"},{"name":"networks","in":"query","schema":{"type":"array","items":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]}},"style":"form","explode":false},{"name":"creator_ids","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Creator ids (`CreatorCard.creator_id`) of tracked creators."},{"name":"formats","in":"query","schema":{"type":"array","items":{"type":"string","enum":["image","video","carousel","reel","short","post","story","article","poll","text"]}},"style":"form","explode":false,"description":"A format that exists on none of the selected networks matches nothing."},{"name":"hashtags","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"With or without `#`."},{"name":"mentions","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Account handles, with or without `@`."},{"name":"keywords","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Case-insensitive match inside the caption."},{"name":"sort","in":"query","schema":{"type":"string","enum":["most_recent","most_popular","most_liked","most_commented","most_shared","best_er","emv"],"default":"most_recent"},"description":"`most_popular` = views + engagements; `best_er` = engagement rate."},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"One page of posts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PostSummary"}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/CursorPagination"},"start_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true}}}]}}},"examples":{"posts":{"$ref":"#/components/examples/TrackerPostsPage"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/DiscoveryForbidden"},"404":{"description":"- `not_found` — no such tracker in this workspace.\n- `search_not_found` — the cursor's feed doesn't exist or belongs to another workspace.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notFound":{"summary":"not_found","value":{"error":{"code":"not_found","message":"Tracker not found.","status":404,"details":[]}}},"searchNotFound":{"summary":"search_not_found","value":{"error":{"code":"search_not_found","message":"This feed was not found. Start over without a cursor.","status":404,"details":[]}}}}}}},"410":{"description":"`search_expired` — the feed is closed: it was idle more than 10 minutes, its last page was already served, or the workspace opened more than 10 feeds and this one was the least recently paged. Start over without a cursor.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchExpired":{"summary":"search_expired","value":{"error":{"code":"search_expired","message":"This feed expired: a cursor stays valid 10 minutes after the call that returned it. Start over without a cursor.","status":410,"details":[]}}}}}}},"422":{"description":"- `invalid_parameters` — the query doesn't match the schema, a cursor was sent with other parameters, or the custom period is out of bounds (start in the future or more than 730 days ago, longer than 366 days, start after end).\n- `invalid_cursor` — not a cursor this API issued, or another tracker's.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"Invalid enum value. Expected 'most_recent' | 'most_popular' | 'most_liked' | 'most_commented' | 'most_shared' | 'best_er' | 'emv', received 'recent'","status":422,"details":[{"field":"sort","reason":"Invalid enum value. Expected 'most_recent' | 'most_popular' | 'most_liked' | 'most_commented' | 'most_shared' | 'best_er' | 'emv', received 'recent'"}]}}},"windowTooLong":{"summary":"invalid_parameters (custom period)","value":{"error":{"code":"invalid_parameters","message":"A custom window spans at most 366 days.","status":422,"details":[{"field":"end_date","reason":"A custom window spans at most 366 days."}]}}},"invalidCursor":{"$ref":"#/components/examples/InvalidCursor"},"otherTrackersCursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"This cursor belongs to another tracker's feed.","status":422,"details":[]}}}}}}},"429":{"$ref":"#/components/responses/SearchRateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/SearchUnavailable"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Favikon API key, prefixed with `fav_`. Generate one from Settings → Connections → API Access."}},"parameters":{"CampaignId":{"name":"campaignId","in":"path","required":true,"description":"MongoDB ObjectId of the campaign","schema":{"type":"string","pattern":"^[a-f0-9]{24}$"},"example":"6702b2c3d4e5f6a7b8c9d0e1"},"Page":{"name":"page","in":"query","description":"Page number (1-indexed)","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","description":"Items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},"RankingCategory":{"name":"category","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Category slug (`GET /filters/taxonomy`). The whole leaderboard when omitted.","example":"tech"},"RankingNiche":{"name":"niche","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Niche slug, inside `category` (required with it). All niches when omitted."},"RankingNetwork":{"name":"network","in":"query","schema":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"description":"Rank on one network. All networks when omitted."},"RankingLocation":{"name":"location","in":"query","schema":{"type":"string","pattern":"^[a-z0-9-]+$"},"description":"Location slug (`GET /filters/locations`): a country, a continent or a group. Worldwide when omitted.","example":"france"},"RankingPerPage":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Rows per page."},"SegmentId":{"name":"segmentId","in":"path","required":true,"schema":{"type":"string"},"description":"The segment's id.","example":"6703a1b2c3d4e5f6a7b8c9d0"},"TrackerId":{"name":"trackerId","in":"path","required":true,"schema":{"type":"string"},"description":"The tracker's id.","example":"6703c1d2e3f4a5b6c7d8e9f0"},"TrackerPeriod":{"name":"period","in":"query","schema":{"type":"string","enum":["last_7_days","last_30_days","last_90_days","last_6_months","last_12_months"],"default":"last_90_days"},"description":"A preset period ending now. Not with `start_date` / `end_date`."},"TrackerStartDate":{"name":"start_date","in":"query","schema":{"type":"string","example":"2026-01-01"},"description":"Start of a custom period (ISO 8601 date or date-time). Requires `end_date`. A custom period is whole UTC days: the start is snapped to 00:00 UTC of its day. It can't be in the future, at most 730 days ago, and the period spans at most 366 days — otherwise `422 invalid_parameters`."},"TrackerEndDate":{"name":"end_date","in":"query","schema":{"type":"string","example":"2026-03-31"},"description":"End of a custom period (ISO 8601 date or date-time). Requires `start_date`. Snapped to 23:59:59.999 UTC of its day, and capped at today. Must be on or after `start_date`'s day."}},"schemas":{"Meta":{"type":"object","properties":{"api_version":{"type":"string","example":"v1"},"credits":{"type":"object","description":"Credits balance and cost context. Present on enrich/creators responses and on campaign write responses (where cost is always 0).","properties":{"remaining":{"type":"integer","nullable":true,"description":"Your current Favikon credit balance (regular + extra).","example":487},"cost":{"type":"integer","description":"Credits charged by the request that produced this data. On POST /enrich it is the maximum possible charge (3); on the enrichment GETs it echoes what the originating run actually consumed (0, 2 or 3; always 0 for a `failed` run, which is refunded) — the GET itself never charges; on free endpoints it is 0.","example":3}}}}},"PaginatedMeta":{"type":"object","properties":{"api_version":{"type":"string","example":"v1"},"page":{"type":"integer","example":1},"per_page":{"type":"integer","example":20},"total":{"type":"integer","example":142},"total_pages":{"type":"integer","example":8}}},"EnrichInput":{"type":"object","description":"Provide exactly one identifier — either a Favikon `creatorId` or\none of the handle/URL fields. Handle fields accept a bare handle\n(`bianca.d`, `@bianca.d`, `marc-richard`) or a full profile URL\n(`https://instagram.com/bianca.d`,\n`https://linkedin.com/in/marc-richard`). `email` and `platform`\nare reserved identifier fields, rejected with a `400` in v1.\n","additionalProperties":false,"properties":{"creatorId":{"type":"string","pattern":"^[a-f0-9]{24}$","description":"Favikon GlobalInfluencer id (e.g. from a previous\n`GET /lists/{id}/contacts` or `GET /campaigns/{id}/creators`\nresponse). Use this to refresh a known creator without\nlooking up their handle. The 30-day no-double-charge gating\nstill applies — if you've already paid for this creator's\nprofile recently, the run is free.\n","example":"6524b53cfa6624efbeeef72a"},"linkedinHandle":{"type":"string","description":"LinkedIn profile URL or bare handle (e.g. `marc-richard`).","example":"https://www.linkedin.com/in/marc-richard/"},"instagramHandle":{"type":"string","example":"bianca.d"},"tiktokHandle":{"type":"string","example":"@amauryguichon"},"youtubeHandle":{"type":"string","example":"@favikon"},"xHandle":{"type":"string","example":"kmbappe"}}},"Enrichment":{"type":"object","properties":{"enrichment_id":{"type":"string"},"bulk_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","done","failed"]},"input":{"type":"object","properties":{"network":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","twitter"]},"username":{"type":"string"}}},"creator_id":{"type":"string","nullable":true,"description":"GlobalInfluencer id once the creator has been resolved (null while pending)."},"data":{"$ref":"#/components/schemas/EnrichmentData"},"error":{"type":"object","nullable":true,"description":"Why a `failed` enrichment failed (null otherwise). `code` is one of `insufficient_credits`, `key_owner_cannot_spend`, `creator_not_found`, `ingest_limit_reached` (daily limit of new creators fetched; resets at midnight UTC), `ingest_in_progress` / `ingest_unavailable` (retry), `key_not_scoped`, `enrich_pipeline_failure`, or a network code (`not_found`, `account_deleted`, `private_account`, `restricted_account`, `empty_posts`). A failed enrichment is never charged.","properties":{"code":{"type":"string","example":"ingest_limit_reached"},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"EnrichmentData":{"type":"object","nullable":true,"description":"Frozen snapshot of the creator at enrichment time. Fields are populated\nbest-effort — missing values are omitted or null depending on the source.\n\nExceptions, computed when you read them (never frozen): `email` and\n`audience`, plus the profile's ratings and ranks —\n`stats.<platform>.ratings`, `insights.brand_safety_label` and\n`rankings` (see \"Ratings & ranks\"). Those three come with\n`GET /enrich/{enrichmentId}` once `done` and with\n`GET /creators/{creatorId}`; bulk results don't carry them.\n","properties":{"creator_id":{"type":"string"},"name":{"type":"string","nullable":true},"picture_url":{"type":"string","format":"uri","nullable":true},"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 country code"},"language":{"type":"string","nullable":true},"age":{"type":"integer","nullable":true},"gender":{"type":"string","nullable":true,"enum":["male","female",null]},"job_title":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"description":"The email on your workspace's contact — the same value the app\nand CSV export show, so surfaces never disagree. A CHARGED\nenrichment runs the same email discovery the app's Find action\nruns (bundled in the 3 credits, asynchronous — emails Favikon\nalready knows resolve near-instantly, fresh searches may land\nafter this snapshot). `null` when no email is known yet.\n"},"email_status":{"type":"string","nullable":true,"enum":["found","searching","not_found",null],"description":"Disambiguates a missing email. `found` — email present.\n`searching` — a charged enrichment fired discovery and it is\nstill in flight (keep polling). `not_found` — searched,\nnothing found; a 30-day cooldown is armed. `null` — never\nsearched by this workspace. (List rows carry no run context,\nso they never report `searching`.)\n"},"handles":{"type":"object","description":"Platform handles keyed by network (`twitter` → `x`). Only networks\nwhere we have a handle are included. Beyond the 5 core networks,\n`twitch`, `pinterest` and `substack` keys can also appear here and\nin `scores.per_network` / `stats`. These are the creator's LIVE\nidentity from Favikon's global record — renames and merges are\nreflected immediately, so they can differ from an app CSV export,\nwhich snapshots handles as of the contact's last enrichment.\nYouTube is the `@handle` (the app may show the `UC…` channel URL\nfor the same channel).\n","additionalProperties":{"type":"string"},"example":{"instagram":"fantinelatreille","tiktok":"fantinelatreille","linkedin":"fantine-latreille-09894121b"}},"scores":{"type":"object","properties":{"global":{"type":"integer","nullable":true,"description":"Global Authority score (0-10 000)."},"per_network":{"type":"object","additionalProperties":{"type":"integer"}},"authenticity":{"type":"object","description":"Only available on `linkedin` and `x`.","additionalProperties":{"type":"object","properties":{"overall":{"type":"number","nullable":true},"followers":{"type":"number","nullable":true},"engagement":{"type":"number","nullable":true},"content":{"type":"number","nullable":true},"ai_content":{"type":"number","nullable":true},"expertise":{"type":"number","nullable":true}}}}}},"stats":{"type":"object","description":"Per-network performance metrics. Only networks with at least one\npopulated metric are included — followers alone qualifies, so a\nfreshly ingested or low-activity creator can legitimately show a\nfollower count with zero engagement and null averages (the rest\nfills in as Favikon's engine finishes analyzing them). These are\nthe SAME figures as your\nworkspace's Contacts table and CSV export — the API mirrors that\nsurface exactly. The profile page's overview computes some\nmetrics (notably engagement rate) over a 12-month window and can\nlegitimately show different values.\n","additionalProperties":{"type":"object","properties":{"followers":{"type":"integer","nullable":true},"follower_growth":{"type":"number","nullable":true,"description":"Percent (7.62 = +7.62 %)."},"engagement":{"type":"integer","nullable":true,"description":"Engagement (likes + comments + shares) computed by Favikon's\nscoring pipeline over its own sampling window — the same\nfigure as the Engagement column of your Contacts table. NOT\nthe sum of avg_likes + avg_comments + avg_shares below —\nthose are averaged over a different (recent-posts) window,\nso the two can legitimately differ.\n"},"engagement_rate":{"type":"number","nullable":true,"description":"Percent (20.92 = 20.92 %). engagement ÷ current followers —\nthe same figure as your Contacts table and CSV export. The\nprofile page's overview uses a 12-month window and can show\na different (usually lower) rate.\n"},"total_posts_last_90d":{"type":"integer","nullable":true},"post_price_estimate":{"type":"integer","nullable":true,"description":"Estimated price per sponsored post (currency inherits caller's workspace)."},"avg_posts_per_month":{"type":"number","nullable":true},"avg_posts_per_week":{"type":"number","nullable":true},"avg_views":{"type":"integer","nullable":true,"description":"Average per post over the recent-posts window (~last 6 months). Applies to avg_likes / avg_comments / avg_shares too."},"avg_likes":{"type":"integer","nullable":true},"avg_comments":{"type":"integer","nullable":true},"avg_shares":{"type":"integer","nullable":true},"ratings":{"allOf":[{"$ref":"#/components/schemas/PerformanceRatings"}],"nullable":true,"description":"The profile's Performance-tab badges for this platform, over\nthe last year — computed at read time (see \"Ratings & ranks\").\n`null` on a platform without a Performance tab, or while\n`meta.ratings_status` is `deferred`.\n"}}}},"insights":{"type":"object","description":"AI-generated creator insights (oa_v3, oa_v2 fallback). Fields are `null` when the creator hasn't been AI-analyzed yet.","properties":{"description":{"type":"string","nullable":true},"brand_safety":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"0–100. Higher is safer."},"brand_safety_label":{"type":"string","nullable":true,"enum":["Very Safe","Safe","Caution","Risky",null],"description":"The app's label for `brand_safety`: 76–100 `Very Safe`, 50–75\n`Safe`, 25–49 `Caution`, 0–24 `Risky`. `null` when\n`brand_safety` is. Computed at read time.\n"},"tone":{"type":"string","nullable":true,"description":"Creator's content style/tone (e.g. \"informative\", \"humorous\")."},"positivity":{"type":"object","nullable":true,"properties":{"label":{"type":"string","nullable":true},"level":{"type":"number","nullable":true}}},"collab_openness":{"type":"string","nullable":true,"description":"Likelihood of brand collaboration (e.g. \"high\", \"medium\", \"low\")."}}},"topics":{"type":"array","description":"Free-text content themes inferred by Favikon's AI from the\ncreator's posts (e.g. \"Giveaways\", \"Beast Games\"). These are NOT\ntaxonomy values — do not match them against a fixed list. For the\nFavikon category taxonomy, use `niches` instead.\n","items":{"type":"string"}},"niches":{"type":"array","description":"The creator's Favikon category taxonomy (e.g. \"Creator Economy\",\n\"Pranks & Challenges\"). Every entry is a real Favikon category, so\nthese are safe to match on. Previously these values were merged\ninto `topics`; they are now returned separately.\n","items":{"type":"string"}},"audience":{"type":"object","description":"Audience demographics per network (instagram / tiktok / youtube).\nIncluded by a CHARGED enrichment (fresh 3-credit unlock — same as\nthe dashboard's reveal flow); free re-runs inside the 30-day\nwindow mirror the audience your workspace already has. Empty\nobject when no audience is available yet (never-charged creator,\nor the platform cannot compute it).\n","additionalProperties":{"type":"object","properties":{"top_countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"percentage":{"type":"number"}}}},"top_cities":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"percentage":{"type":"number"}}}},"top_languages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"percentage":{"type":"number"}}}},"gender_split":{"type":"object","properties":{"male":{"type":"number","nullable":true},"female":{"type":"number","nullable":true}}}}}},"partnered_brands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"picture_url":{"type":"string","format":"uri","nullable":true},"occurrences":{"type":"integer"}}}},"last_refreshed_at":{"type":"string","format":"date-time","nullable":true,"description":"When Favikon last RECOMPUTED this creator's stats from its data\nstore (an enrichment or refresh run). The underlying platform\ndata may be older — Favikon's engine refreshes it on its own\nfreshness policy, independent of this timestamp.\n"},"last_enriched_at":{"type":"string","format":"date-time","nullable":true,"description":"When the full enrichment pipeline last ran for your workspace's contact."},"rankings":{"type":"array","description":"The creator's best ranking boards, best rank first (up to 9) — the\nprofile's Rankings card. Uncapped: `rank` is the creator's own\nposition, beyond the top 200 the board listing stops at. `[]` when\nthe creator has no ranked board. Computed at read time (see\n\"Ratings & ranks\").\n","items":{"$ref":"#/components/schemas/CreatorRanking"}}}},"RatingsStatus":{"type":"string","nullable":true,"enum":["ready","deferred",null],"description":"Whether every rating was served: `ready`, or `deferred` — some could\nnot be computed within this request and keep computing; read again a\nfew seconds later. `null` on an enrichment that isn't `done`.\n"},"PerformanceRatings":{"type":"object","description":"The profile's Performance-tab badges for one platform. An entry is\n`null` when the app shows no badge for it.\n","properties":{"period":{"type":"string","enum":["last_year"],"description":"The window every entry is computed over."},"computed_at":{"type":"string","format":"date-time","description":"When these ratings were computed (cached up to 24 hours)."},"engagement_rate":{"allOf":[{"$ref":"#/components/schemas/PerformanceRating"}],"nullable":true,"description":"`value`: engagement per post ÷ followers × 100 (%), against the peers' own engagement rates."},"engagement":{"allOf":[{"$ref":"#/components/schemas/PerformanceRating"}],"nullable":true,"description":"`value`: engagement (likes + comments + shares) per post."},"follower_growth":{"allOf":[{"$ref":"#/components/schemas/PerformanceRating"}],"nullable":true,"description":"`value`: follower growth over the year (%). Fixed bands, so `peer_median` is always `null`."},"posting":{"allOf":[{"$ref":"#/components/schemas/PerformanceRating"}],"nullable":true,"description":"`value`: posts per `unit`."}}},"PerformanceRating":{"type":"object","properties":{"rating":{"type":"string","enum":["excellent","good","average","below_average","poor","very_poor"]},"label":{"type":"string","enum":["Excellent","Good","Average","Below Average","Poor","Very Poor"],"description":"The text the app shows on the badge."},"value":{"type":"number","nullable":true,"description":"The creator's value — the number the app shows beside the badge."},"peer_median":{"type":"number","nullable":true,"description":"The median of ~100 similar creators over the same window, same formula."},"unit":{"type":"string","nullable":true,"enum":["day","week","month",null],"description":"`posting` only: the period of `value`."}}},"CreatorRanking":{"type":"object","properties":{"rank":{"type":"integer","description":"Creators on the board with a strictly higher Favikon score, + 1 (ties share a rank)."},"board_size":{"type":"integer","nullable":true,"description":"Creators on the board."},"top_percent":{"type":"integer","nullable":true,"minimum":1,"maximum":100,"description":"`max(round(rank ÷ board_size × 100), 1)` — the app's \"Top N%\"."},"board":{"type":"object","properties":{"top_id":{"type":"string","description":"The board's slug — `meta.top_id` of `GET /api/v1/rankings/creators`."},"network":{"type":"string","nullable":true,"enum":["instagram","tiktok","youtube","linkedin","x",null],"description":"`null` on a cross-network board."},"country":{"type":"object","nullable":true,"properties":{"code":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 (`null` on a region without one, e.g. Quebec)."},"name":{"type":"string","nullable":true}}},"language":{"type":"string","nullable":true,"description":"A worldwide board narrowed to a language (e.g. \"English\")."},"industry":{"type":"string","nullable":true},"niche":{"type":"string","nullable":true},"gender":{"type":"string","nullable":true,"enum":["Male","Female","Other",null]}}}}},"CampaignAnalytics":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"currency":{"type":"string"},"start_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"url":{"type":"string","format":"uri"}}},"summary":{"type":"object","properties":{"total_posts":{"type":"integer"},"total_creators":{"type":"integer"},"total_engagement":{"type":"integer"},"total_views":{"type":"integer"},"total_emv":{"type":"number","format":"float"}}},"cost":{"type":"object","properties":{"budget":{"type":"number"},"budget_engaged":{"type":"number"},"cpm":{"type":"number"},"cpe":{"type":"number"},"cpv":{"type":"number"}}},"platform_breakdown":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PlatformMetrics"}},"time_series":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"posts":{"type":"integer"},"engagement":{"type":"integer"}}}},"creator_funnel":{"type":"object","properties":{"activated":{"type":"integer"},"replied":{"type":"integer"},"accepted":{"type":"integer"},"published":{"type":"integer"}}}}},"PlatformMetrics":{"type":"object","properties":{"posts":{"type":"integer"},"engagement":{"type":"integer"},"engagement_rate":{"type":"number"},"views":{"type":"integer"},"emv":{"type":"number"},"cpe":{"type":"number"},"cpv":{"type":"number"},"budget_engaged":{"type":"number"}}},"AddCampaignCreatorsInput":{"type":"object","description":"Body for `POST /campaigns/{campaignId}/creators`.\n\nYou must provide **at least one** of `creator_ids` or `handles`\n(or both). The combined total is capped at **100** items per request.\n\n- Use `creator_ids` when you already have the Favikon creator id\n  (e.g. from `GET /campaigns/{id}/creators` or `GET /enrich/{id}`).\n  Immediate add, no engine call.\n- Use `handles` when you only have a social handle or URL. The API\n  resolves it to a creator id — via indexed lookup if we already\n  know them, or by ingesting from the social network otherwise.\n  Ingestion is free (no credits charged) — campaign add never\n  triggers the paid enrichment pipeline.\n","properties":{"creator_ids":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[a-f0-9]{24}$"},"description":"GlobalInfluencer ids."},"handles":{"type":"array","maxItems":100,"description":"Handles or URLs to resolve. Each item must provide exactly one identifier (same schema as `POST /enrich` input).","items":{"type":"object","properties":{"linkedinHandle":{"type":"string","description":"LinkedIn profile URL or bare handle (e.g. `marc-richard`)."},"instagramHandle":{"type":"string"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"xHandle":{"type":"string"}}}},"step_status_slug":{"type":"string","description":"Pipeline stage slug. Defaults to the campaign's `default` step (or `\"new\"` if no stepStatuses are configured)."}}},"CampaignCreatorResult":{"type":"object","description":"Per-item outcome in an add-creators response.","properties":{"creator_id":{"type":"string","nullable":true,"description":"Resolved GlobalInfluencer id. `null` for handle items the API couldn't resolve."},"input_handle":{"type":"object","nullable":true,"description":"Echo of the original handle input. Present only for items submitted via `handles`. Absent for items submitted as `creator_ids`.","properties":{"linkedinHandle":{"type":"string"},"instagramHandle":{"type":"string"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"xHandle":{"type":"string"}}},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["added","already_in_campaign","not_found","failed"]},"custom_creator_campaign_id":{"type":"string","nullable":true,"description":"Present on `added` and `already_in_campaign`."},"step_status_slug":{"type":"string","nullable":true,"description":"Pipeline stage the creator was placed in (`added` only)."},"added_at":{"type":"string","format":"date-time","nullable":true},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"CampaignCreatorsMutationResult":{"type":"object","description":"Return shape for `POST /campaigns/{campaignId}/creators`.","properties":{"campaign_id":{"type":"string"},"summary":{"type":"object","description":"Count rollup across all input items.","properties":{"added":{"type":"integer"},"already_in_campaign":{"type":"integer"},"not_found":{"type":"integer"},"failed":{"type":"integer"}}},"creators":{"type":"array","items":{"$ref":"#/components/schemas/CampaignCreatorResult"}},"contacts_added":{"type":"array","description":"Newly-created contact records (one per creator that wasn't already a contact).","items":{"type":"object","properties":{"creator_id":{"type":"string"},"contact_id":{"type":"string","nullable":true}}}}}},"CampaignCreatorDeleteResult":{"type":"object","description":"Per-item outcome in a bulk-delete response.","properties":{"creator_id":{"type":"string"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["removed","not_in_campaign","not_found","failed"]},"custom_creator_campaign_id":{"type":"string","nullable":true,"description":"Present on `removed`."},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"CampaignCreatorsDeleteResult":{"type":"object","description":"Return shape for `POST /campaigns/{campaignId}/creators/bulk-delete`.","properties":{"campaign_id":{"type":"string"},"summary":{"type":"object","properties":{"removed":{"type":"integer"},"not_in_campaign":{"type":"integer"},"not_found":{"type":"integer"},"failed":{"type":"integer"}}},"creators":{"type":"array","items":{"$ref":"#/components/schemas/CampaignCreatorDeleteResult"}}}},"ContactList":{"type":"object","description":"A saved grouping of contacts owned by the workspace.","properties":{"list_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"contact_count":{"type":"integer","description":"Number of active contacts in this list."},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"ListContactResult":{"type":"object","description":"Per-item outcome in a list add-contacts response.","properties":{"creator_id":{"type":"string","nullable":true,"description":"Resolved GI id. `null` when a handle item couldn't be resolved."},"input_handle":{"type":"object","nullable":true,"description":"Echo of the original handle. Present only for items submitted via `handles`.","properties":{"linkedinHandle":{"type":"string"},"instagramHandle":{"type":"string"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"xHandle":{"type":"string"}}},"contact_id":{"type":"string","nullable":true,"description":"Customer-scoped Contact id. Absent when the creator wasn't resolvable."},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["added","already_in_list","not_found","failed"]},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ListContactsMutationResult":{"type":"object","description":"Return shape for `POST /lists/{listId}/contacts`.","properties":{"list_id":{"type":"string"},"summary":{"type":"object","properties":{"added":{"type":"integer"},"already_in_list":{"type":"integer"},"not_found":{"type":"integer"},"failed":{"type":"integer"}}},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ListContactResult"}},"contacts_added":{"type":"array","description":"Newly-created Contact rows for creators that weren't contacts of this workspace yet.","items":{"type":"object","properties":{"creator_id":{"type":"string"},"contact_id":{"type":"string"}}}}}},"ListContactDeleteResult":{"type":"object","description":"Per-item outcome in a list bulk-delete response.","properties":{"creator_id":{"type":"string","nullable":true,"description":"Resolved GI id. `null` for handle items the API couldn't resolve to a known creator."},"input_handle":{"type":"object","nullable":true,"description":"Echo of the original handle. Present only for items submitted via `handles`.","properties":{"linkedinHandle":{"type":"string"},"instagramHandle":{"type":"string"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"xHandle":{"type":"string"}}},"contact_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["removed","not_in_list","not_found","failed"]},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ListContactsDeleteResult":{"type":"object","description":"Return shape for `POST /lists/{listId}/contacts/bulk-delete`.","properties":{"list_id":{"type":"string"},"summary":{"type":"object","properties":{"removed":{"type":"integer"},"not_in_list":{"type":"integer"},"not_found":{"type":"integer"},"failed":{"type":"integer"}}},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ListContactDeleteResult"}}}},"ListContact":{"type":"object","description":"Slim public shape for a contact appearing inside a list. Includes\nonly the basics — id, name, avatar, demographics, enrichment\ntimestamps. Returned by `GET /lists/{listId}/contacts`.\n\n**Need full CRM fields** (pipeline status, automations, deliverables,\ncustom properties)? Use `GET /campaigns/{campaignId}/creators`\ninstead — that returns the richer `Creator` schema.\n","properties":{"contact_id":{"type":"string","nullable":true,"description":"Customer-scoped Contact id."},"creator_id":{"type":"string","nullable":true,"description":"Favikon GlobalInfluencer id. Use this in `POST /campaigns/{id}/creators` or `POST /lists/{id}/contacts`."},"name":{"type":"string","nullable":true},"avatar_url":{"type":"string","format":"uri","nullable":true},"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2."},"job_title":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"description":"The email currently stored on your workspace's contact — the\nsame value the app and CSV export show, so surfaces never\ndisagree. This endpoint is a pure read: it never triggers\ndiscovery or charges anything. Emails get onto the contact via\na charged `POST /enrich` (discovery bundled in the 3 credits)\nor the app's Find action. `null` when no email is known yet.\n"},"email_status":{"type":"string","nullable":true,"enum":["found","searching","not_found",null],"description":"Disambiguates a missing email. `found` — email present.\n`searching` — a charged enrichment fired discovery and it is\nstill in flight (keep polling). `not_found` — searched,\nnothing found; a 30-day cooldown is armed. `null` — never\nsearched by this workspace. (List rows carry no run context,\nso they never report `searching`.)\n"},"followers_count":{"type":"integer","nullable":true},"last_enriched_at":{"type":"string","format":"date-time","nullable":true},"last_refreshed_at":{"type":"string","format":"date-time","nullable":true}}},"Creator":{"type":"object","description":"Full CRM view of a creator inside a campaign — pipeline status,\ncontact data, socials, demographics, niches, automations, custom\nproperties. Returned by `GET /campaigns/{campaignId}/creators`.\n\n**Lighter alternative** for non-campaign list views:\n`GET /lists/{listId}/contacts` returns the slimmer `ListContact`\nschema.\n\n**Note** `creator_id` here is a GlobalInfluencer id — use it as\n`creator_ids[]` in `POST /campaigns/{id}/creators` /\n`POST /lists/{id}/contacts`, or as the path param in\n`DELETE /campaigns/{id}/creators/{creatorId}` /\n`DELETE /lists/{id}/contacts/{creatorId}`. The\n`custom_creator_campaign_id` field is the per-campaign pipeline\nrow id, useful for correlating with deliverables/outreach.\n","properties":{"creator_id":{"type":"string","description":"GlobalInfluencer id. Use this as `creator_ids[]` in `POST /creators` and as the path param in `DELETE /creators/{creatorId}`."},"custom_creator_campaign_id":{"type":"string","nullable":true,"description":"Per-campaign pipeline row id. Useful for correlating with deliverables/outreach in other endpoints."},"name":{"type":"string","nullable":true},"avatar_url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","nullable":true},"automations":{"type":"array","items":{"type":"object","properties":{"channels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","nullable":true,"description":"Raw outreach status. Common values include draft, active, paused, completed, failed — but the set is not closed; treat unknown values as opaque."},"date":{"type":"string","format":"date-time"}}}},"post_count":{"type":"integer"},"platforms":{"type":"array","items":{"type":"string"}},"price":{"type":"object","nullable":true,"properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"formats":{"type":"array","items":{"type":"string"}},"post_date":{"type":"string","format":"date-time","nullable":true},"shipping_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"payment_condition":{"type":"string","nullable":true},"payment_date":{"type":"string","format":"date-time","nullable":true},"email":{"type":"string","format":"email","nullable":true,"description":"The email on the workspace's own contact for this creator. `null` when the creator has no contact in the workspace (or it has no email) — run `POST /enrich` to look for one."},"enriched_at":{"type":"string","format":"date-time","nullable":true},"socials":{"type":"object","properties":{"instagram":{"$ref":"#/components/schemas/SocialHandle"},"linkedin":{"$ref":"#/components/schemas/SocialHandle"},"tiktok":{"$ref":"#/components/schemas/SocialHandle"},"youtube":{"$ref":"#/components/schemas/SocialHandle"},"x":{"$ref":"#/components/schemas/SocialHandle"}}},"score":{"type":"integer","nullable":true},"tier":{"type":"integer","nullable":true,"description":"Score tier 1-10 (1 = highest)"},"followers":{"type":"number","nullable":true,"description":"Total followers across the creator's networks. `null` when no network has an audience yet."},"language":{"type":"string","nullable":true},"gender":{"type":"string","enum":["male","female","non_binary",null],"nullable":true},"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 country code"},"job_title":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"industries":{"type":"array","items":{"type":"string"}},"niches":{"type":"array","items":{"type":"string"}},"growth":{"type":"number","nullable":true,"description":"Follower growth rate (decimal, e.g. 0.0101 = +1.01%)"},"custom_properties":{"type":"object","additionalProperties":true}}},"SocialHandle":{"type":"object","nullable":true,"properties":{"handle":{"type":"string","nullable":true},"url":{"type":"string","format":"uri"}}},"CreatorAnalytics":{"type":"object","properties":{"creator_id":{"type":"string"},"name":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"metrics":{"type":"object","properties":{"posts":{"type":"integer"},"engagement":{"type":"integer"},"engagement_rate":{"type":"number","description":"Decimal ratio (0.001 = 0.1%)"},"views":{"type":"integer"},"emv":{"type":"number"},"cpm":{"type":"number"},"cpe":{"type":"number"},"cpv":{"type":"number"},"website_visits":{"type":"integer","nullable":true,"description":"Only populated if Google Analytics is connected"},"conversion_events":{"type":"integer","nullable":true,"description":"Only populated if a conversion event is configured"}}},"cost":{"type":"object","properties":{"budget":{"type":"number"},"budget_engaged":{"type":"number"}}}}},"Post":{"type":"object","properties":{"post_id":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"status":{"type":"string","enum":["approved","scheduled","pending"],"description":"Post status: approved (live), scheduled (planned), pending (awaiting review)"},"post_url":{"type":"string","format":"uri","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"creator":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"avatar_url":{"type":"string","format":"uri"}}},"content_preview":{"type":"string","nullable":true,"description":"Caption truncated to 200 characters"},"media_type":{"type":"string","nullable":true,"description":"Post format (post, story, reel, video, etc.)"},"hashtags":{"type":"array","items":{"type":"string"}},"mentions":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object","properties":{"views":{"type":"integer"},"engagement":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"engagement_rate":{"type":"number","description":"Decimal ratio (0.001 = 0.1%)"},"emv":{"type":"number"}}}}},"PostDetail":{"allOf":[{"$ref":"#/components/schemas/Post"},{"type":"object","properties":{"content":{"type":"string","nullable":true,"description":"Full caption (not truncated)"},"media_url":{"type":"string","format":"uri","nullable":true,"description":"Stable Favikon S3 URL for the post thumbnail, pre-signed for 7 days"}}}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status","details"],"properties":{"code":{"type":"string","example":"invalid_parameters"},"message":{"type":"string","example":"Invalid campaign ID"},"status":{"type":"integer","example":422},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reason":{"type":"string"}}}}}}}},"CreatorRef":{"description":"One creator: a Favikon `creator_id`, or an object with exactly one\nidentifier — `creatorId`, or a network handle / profile URL (see\n\"Resolving handles\"). Handles of creators Favikon doesn't know yet are\nfetched for free.\n","oneOf":[{"type":"string","pattern":"^[a-fA-F0-9]{24}$","example":"63a477561c819689ff4e32f8"},{"type":"object","additionalProperties":false,"minProperties":1,"maxProperties":1,"properties":{"creatorId":{"type":"string"},"instagramHandle":{"type":"string","example":"bianca.d"},"tiktokHandle":{"type":"string"},"youtubeHandle":{"type":"string"},"linkedinHandle":{"type":"string"},"xHandle":{"type":"string"}}}]},"Range":{"type":"object","additionalProperties":false,"description":"Inclusive bounds; either may be omitted. `min` must not exceed `max`.","properties":{"min":{"type":"number"},"max":{"type":"number"}}},"PlatformStats":{"type":"object","additionalProperties":false,"description":"Ranges on one platform's stats. `engagement_rate` and `growth` are percentages (2.5 = 2.5%; `growth` may be negative); `post_frequency` is posts per month; the others are counts (integers ≥ 0).","properties":{"followers":{"$ref":"#/components/schemas/Range"},"growth":{"$ref":"#/components/schemas/Range"},"engagement_rate":{"$ref":"#/components/schemas/Range"},"engagement_per_post":{"$ref":"#/components/schemas/Range"},"views_per_post":{"$ref":"#/components/schemas/Range"},"post_frequency":{"$ref":"#/components/schemas/Range"}}},"SearchFilters":{"type":"object","description":"Filters shared by `POST /lookalikes` and `POST /radar`. Unknown keys are rejected with `422 invalid_parameters`.","properties":{"platforms":{"type":"array","maxItems":5,"items":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"description":"Only creators with an account on every listed platform."},"countries":{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Creator country, ISO 3166-1 alpha-2 codes (any of).","example":["FR","BE"]},"languages":{"type":"array","maxItems":20,"items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Creator language, ISO 639-1 codes (any of).","example":["fr"]},"gender":{"type":"string","enum":["male","female","all"],"default":"all"},"industry":{"type":"string","description":"A Favikon taxonomy industry id. Not combinable with `niches`."},"niches":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Favikon taxonomy niche ids (any of). Not combinable with `industry`."},"tiers":{"type":"array","maxItems":10,"items":{"type":"integer","minimum":1,"maximum":10},"description":"Favikon tiers (1 = top) — any of."},"verified_only":{"type":"boolean","description":"Only platform-verified creators."},"hide_saved":{"type":"boolean","description":"Leave out creators already saved in the key's workspace (its CRM). Applied to the whole result list, so pages stay full and `total` reflects it."},"platform_stats":{"type":"object","additionalProperties":false,"description":"Stat ranges per platform.","properties":{"instagram":{"$ref":"#/components/schemas/PlatformStats"},"tiktok":{"$ref":"#/components/schemas/PlatformStats"},"youtube":{"$ref":"#/components/schemas/PlatformStats"},"linkedin":{"$ref":"#/components/schemas/PlatformStats"},"x":{"$ref":"#/components/schemas/PlatformStats"}}}}},"LookalikeFilters":{"description":"The shared search filters, plus lookalike-only ones.","allOf":[{"$ref":"#/components/schemas/SearchFilters"},{"type":"object","properties":{"profile_type":{"type":"string","enum":["creators","brands","all"],"default":"all"},"safe_search":{"type":"boolean","default":true,"description":"`false` also returns creators flagged as adult or sensitive."}}}]},"RadarFilters":{"description":"The shared search filters, plus Radar-only ones.","allOf":[{"$ref":"#/components/schemas/SearchFilters"},{"type":"object","properties":{"posted_within_days":{"type":"integer","minimum":1,"maximum":3650,"description":"Only count mentions posted in the last N days."},"instagram_post_format":{"type":"string","enum":["post","reel","story","carousel"],"description":"Only count Instagram mentions of this format."}}}]},"SearchCreator":{"type":"object","description":"A creator in search results. Stats are numbers; any may be null for a creator Favikon has little data on.","properties":{"creator_id":{"type":"string","example":"656c43ab0c36863cb1ca11c5"},"name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true,"description":"Pre-signed URL, valid 7 days."},"title":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2, upper case.","example":"FR"},"tier":{"type":"integer","nullable":true,"minimum":1,"maximum":10,"description":"Favikon tier (1 = top)."},"profile_url":{"type":"string","description":"The creator's Favikon profile."},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"followers":{"type":"integer","nullable":true},"engagement_rate":{"type":"number","nullable":true,"description":"Engagement per post / followers, as a percentage.","example":2.5},"profile_url":{"type":"string","nullable":true}}}},"in_crm":{"type":"boolean","description":"Already saved in the key's workspace."}}},"CursorPagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"page_size":{"type":"integer","example":25},"total":{"type":"integer","description":"Creators in the whole search.","example":312},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true,"description":"Send as `{ \"cursor\": … }` for the next page; `null` on the last page."}}},"SearchMeta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/CursorPagination"}}}]},"SeedsProcessing":{"type":"object","properties":{"status":{"type":"string","enum":["seeds_processing"]},"retry_after":{"type":"integer","description":"Seconds to wait before sending the same request again.","example":20},"seeds":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position in the request's `seeds`."},"input":{"$ref":"#/components/schemas/CreatorRef"},"creator_id":{"type":"string","nullable":true,"description":"`null` while a handle is still being fetched."},"status":{"type":"string","enum":["ready","processing"]}}}}}},"BrandsProcessing":{"type":"object","properties":{"status":{"type":"string","enum":["brands_processing"]},"retry_after":{"type":"integer","example":20},"brands":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"input":{"$ref":"#/components/schemas/CreatorRef"},"creator_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["ready","processing"]}}}}}},"RadarBrand":{"type":"object","properties":{"creator_id":{"type":"string"},"name":{"type":"string","nullable":true},"tracked_platforms":{"type":"array","items":{"type":"string","enum":["instagram","tiktok","x","linkedin"]},"description":"Platforms scanned for this brand's mentions — empty means none."}}},"RadarSearchResult":{"type":"object","properties":{"radar_search_id":{"type":"string","nullable":true,"description":"Id of this saved search (24 hours) — for cursor pages and the evidence-posts endpoint. `null` when nothing was found."},"brands":{"type":"array","items":{"$ref":"#/components/schemas/RadarBrand"}},"creators":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SearchCreator"},{"type":"object","properties":{"mention_count":{"type":"integer","description":"Number of the creator's posts that mention the brands.","example":12}}}]}}}},"RadarPost":{"type":"object","properties":{"post_id":{"type":"string","example":"instagram_3215546789012345678"},"platform":{"type":"string","enum":["instagram","tiktok","x","linkedin"]},"url":{"type":"string","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"format":{"type":"string","nullable":true,"description":"Post format as labelled by the platform (e.g. `reel`, `post`, `video`)."},"caption":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"views":{"type":"integer","nullable":true},"likes":{"type":"integer","nullable":true},"comments":{"type":"integer","nullable":true},"shares":{"type":"integer","nullable":true},"engagement_rate":{"type":"number","nullable":true,"description":"Post engagement as a percentage."},"is_brand_partnership":{"type":"boolean","description":"Flagged by the platform as a paid partnership."},"tagged_brand":{"type":"object","nullable":true,"description":"The searched brand this post mentions.","properties":{"creator_id":{"type":"string"},"name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true}}}}},"CreatorSearchFilters":{"description":"The shared search filters, plus creator-search ones. When both `platforms` and `platform_stats` are given, every `platform_stats` platform must be listed in `platforms`.","allOf":[{"$ref":"#/components/schemas/SearchFilters"},{"type":"object","properties":{"profile_type":{"type":"string","enum":["creators","brands","all"],"default":"all"},"safe_search":{"type":"boolean","default":true,"description":"`false` also returns creators flagged as adult or sensitive."},"job_title":{"type":"string","maxLength":100,"description":"Text match on the job title from the creator's LinkedIn profile.","example":"founder"},"company":{"type":"string","maxLength":100,"description":"Text match on the creator's current company.","example":"Stripe"},"linkedin_top_voice":{"type":"boolean","description":"Only LinkedIn Top Voices."}}}]},"ContentCreatorFilters":{"description":"Who made the posts: the shared search filters, plus these. Unsafe posts are always excluded, so there is no `safe_search`.","allOf":[{"$ref":"#/components/schemas/SearchFilters"},{"type":"object","properties":{"profile_type":{"type":"string","enum":["creators","brands","all"],"default":"all"},"job_title":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":100},"linkedin_top_voice":{"type":"boolean"}}}]},"PostFilters":{"type":"object","additionalProperties":false,"description":"Post-level filters. `engagement_rate` is a percentage (2.5 = 2.5%); the other ranges are counts.","properties":{"platforms":{"type":"array","items":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"description":"Posts on any of these platforms."},"published_after":{"type":"string","description":"ISO 8601 date or date-time, inclusive.","example":"2026-06-01"},"published_before":{"type":"string","description":"ISO 8601 date or date-time, inclusive."},"content_type":{"type":"string","enum":["short_video","long_video","image","carousel","text"]},"sponsored":{"type":"boolean","description":"`true` only paid partnerships, `false` only organic posts."},"language":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Post language, ISO 639-1."},"views":{"$ref":"#/components/schemas/Range"},"likes":{"$ref":"#/components/schemas/Range"},"comments":{"$ref":"#/components/schemas/Range"},"shares":{"$ref":"#/components/schemas/Range"},"engagement":{"$ref":"#/components/schemas/Range"},"engagement_rate":{"$ref":"#/components/schemas/Range"}}},"CreatorCard":{"type":"object","description":"The creator card of the Discovery searches. Never contains an email address or a phone number: one found inside a free-text field (`name`, `job_title`, `company`, `description`, a brand name) is replaced by `[redacted]`, and a field left with nothing else is null. Any field may be null for a creator Favikon has little data on.","properties":{"creator_id":{"type":"string","example":"656c43ab0c36863cb1ca11c5"},"name":{"type":"string","nullable":true},"picture_url":{"type":"string","nullable":true,"description":"Pre-signed URL, valid 7 days."},"profile_url":{"type":"string","description":"The creator's Favikon profile."},"is_brand":{"type":"boolean"},"social_links":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x","twitch","pinterest","substack"]},"username":{"type":"string","nullable":true},"url":{"type":"string"},"verified":{"type":"boolean"},"followers":{"type":"integer","nullable":true},"engagement_rate":{"type":"number","nullable":true,"description":"Engagement per post / followers, as a percentage.","example":2.5}}}},"score":{"type":"integer","nullable":true,"description":"Favikon authority score.","example":8120},"tier":{"type":"integer","nullable":true,"minimum":1,"maximum":10,"description":"Favikon tier (1 = top)."},"followers":{"type":"integer","nullable":true,"description":"Followers across platforms."},"language":{"type":"string","nullable":true,"description":"ISO 639-1 (Hebrew as `iw`).","example":"fr"},"gender":{"type":"string","nullable":true,"enum":["female","male","other"]},"country":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2, upper case.","example":"FR"},"age":{"type":"integer","nullable":true},"job_title":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"description":{"type":"string","nullable":true,"description":"A short AI-written summary of who the creator is."},"industry":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"niches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"is_primary":{"type":"boolean"}}}},"associated_brands":{"type":"array","description":"Brands the creator is associated with (at most 5).","items":{"type":"object","properties":{"creator_id":{"type":"string"},"name":{"type":"string"}}}}}},"CreatorResult":{"description":"A creator card in a search result list.","allOf":[{"$ref":"#/components/schemas/CreatorCard"},{"type":"object","properties":{"in_crm":{"type":"boolean","description":"Already saved in the key's workspace."}}}]},"PostSummary":{"type":"object","description":"A post as the Discovery content search returns it, with its creator's card. Hidden metrics (the creator turned them off) are null.","properties":{"post_id":{"type":"string","example":"instagram_3215546789012345678"},"platform":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"url":{"type":"string","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true},"format":{"type":"string","nullable":true,"description":"Post format as labelled by the platform (e.g. `reel`, `post`, `video`, `short`)."},"content_type":{"type":"string","nullable":true,"enum":["short_video","long_video","image","carousel","text"]},"caption":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true,"description":"Pre-signed URL, valid 7 days."},"views":{"type":"integer","nullable":true},"likes":{"type":"integer","nullable":true},"comments":{"type":"integer","nullable":true},"shares":{"type":"integer","nullable":true},"engagement_rate":{"type":"number","nullable":true,"description":"Post engagement as a percentage."},"is_sponsored":{"type":"boolean","description":"Flagged as a paid partnership."},"creator":{"allOf":[{"$ref":"#/components/schemas/CreatorCard"}],"nullable":true}}},"SearchUsage":{"type":"object","description":"The workspace's Discovery results today (UTC).","properties":{"results_today":{"type":"integer","example":250},"daily_limit":{"type":"integer","example":10000}}},"DiscoveryPagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"page_size":{"type":"integer","example":25},"total":{"type":"integer","nullable":true,"description":"Results in the whole search (at most 1,000). `null` for post search, which grows as you page — follow `has_more`.","example":312},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true,"description":"Send as `{ \"cursor\": … }` for the next page; `null` on the last page."}}},"DiscoverySearchMeta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/SearchUsage"},"pagination":{"$ref":"#/components/schemas/DiscoveryPagination"}}}]},"RankingCreator":{"description":"A row of a ranking board.","allOf":[{"$ref":"#/components/schemas/CreatorResult"},{"type":"object","properties":{"rank":{"type":"integer","description":"Position on the board (1 = top).","example":1},"ranking_score":{"type":"number","nullable":true,"description":"The score the board shows — the network score on a network board, else the global authority score."}}}]},"TaxonomyIndustry":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Food & Drink"},"slug":{"type":"string","example":"food-drink"},"niches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"Home Cooking"},"slug":{"type":"string","example":"home-cooking"}}}}}},"StringList":{"type":"array","items":{"type":"string"}},"Segment":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"],"description":"`draft` until committed; `paused` stops the daily refresh and the 30-day renewal."},"rule":{"allOf":[{"$ref":"#/components/schemas/SegmentRule"}],"nullable":true,"description":"The rule, as stored. Segments built in the app may hold settings the API doesn't model (e.g. legacy categories); those are left out."},"exclusions":{"$ref":"#/components/schemas/SegmentExclusions"},"size_limit":{"type":"integer","nullable":true,"description":"Most members the segment keeps; null for a draft."},"member_count":{"type":"integer","nullable":true,"description":"Creators in the segment's list now; null for a draft."},"list_id":{"type":"string","nullable":true,"description":"The segment's list (null until committed). Readable through `GET /lists/{listId}/contacts`, but not listed by `GET /lists`. **Deleting the segment deletes this list.**"},"cost":{"type":"integer","nullable":true,"description":"The 30-day recurring charge, fixed at commit; null for a draft."},"committed_at":{"type":"string","format":"date-time","nullable":true},"next_charge_at":{"type":"string","format":"date-time","nullable":true,"description":"When the next renewal is charged (only while active)."},"charge_failed_at":{"type":"string","format":"date-time","nullable":true,"description":"Set when a renewal couldn't be paid (the segment was paused)."},"refreshed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SegmentRule":{"description":"What the segment matches. `source` picks the engine; the rest is the body of the matching search endpoint. Unknown keys are rejected.","oneOf":[{"$ref":"#/components/schemas/SegmentCreatorSearchRule"},{"$ref":"#/components/schemas/SegmentContentSearchRule"},{"$ref":"#/components/schemas/SegmentLookalikesRule"},{"$ref":"#/components/schemas/SegmentRadarRule"},{"$ref":"#/components/schemas/SegmentRankingsRule"}],"discriminator":{"propertyName":"source","mapping":{"creator_search":"#/components/schemas/SegmentCreatorSearchRule","content_search":"#/components/schemas/SegmentContentSearchRule","lookalikes":"#/components/schemas/SegmentLookalikesRule","radar":"#/components/schemas/SegmentRadarRule","rankings":"#/components/schemas/SegmentRankingsRule"}}},"SegmentCreatorSearchRule":{"type":"object","additionalProperties":false,"required":["source"],"description":"Like `POST /search/creators` — a `prompt` and/or `filters` (no `hide_saved`).","properties":{"source":{"type":"string","enum":["creator_search"]},"prompt":{"type":"string","maxLength":500},"filters":{"$ref":"#/components/schemas/CreatorSearchFilters"}}},"SegmentContentSearchRule":{"type":"object","additionalProperties":false,"required":["source"],"description":"The creators of the posts matching `keywords` and/or `post_filters` (like `POST /search/content`). `semantic` matches one description by meaning; `keyword` matches the words literally, joined by `operator`, and can exclude. Keywords can't contain `\"`; with operator `and`, not the word \"or\".","properties":{"source":{"type":"string","enum":["content_search"]},"keywords":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"One entry in semantic mode."},"exclude_keywords":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"Keyword mode only."},"mode":{"type":"string","enum":["semantic","keyword"],"default":"semantic"},"operator":{"type":"string","enum":["and","or"],"default":"and"},"post_filters":{"$ref":"#/components/schemas/PostFilters"}}},"SegmentLookalikesRule":{"type":"object","additionalProperties":false,"required":["source","seeds"],"description":"Like `POST /lookalikes` (no `hide_saved`).","properties":{"source":{"type":"string","enum":["lookalikes"]},"seeds":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/CreatorRef"},"description":"Read back as creator ids."},"filters":{"$ref":"#/components/schemas/LookalikeFilters"}}},"SegmentRadarRule":{"type":"object","additionalProperties":false,"required":["source","brands"],"description":"The creators who posted about these brands (like `POST /radar`, without filters).","properties":{"source":{"type":"string","enum":["radar"]},"brands":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/CreatorRef"},"description":"Read back as creator ids."}}},"SegmentRankingsRule":{"type":"object","additionalProperties":false,"required":["source"],"description":"A favikon.com ranking's creators, by the slugs of `GET /filters/taxonomy` and `GET /filters/locations`.","properties":{"source":{"type":"string","enum":["rankings"]},"category":{"type":"string"},"niche":{"type":"string","description":"Needs its `category`."},"network":{"type":"string","enum":["instagram","tiktok","youtube","linkedin","x"]},"location":{"type":"string"},"language":{"type":"string","description":"ISO 639-1."},"gender":{"type":"string","enum":["male","female","other"]}}},"SegmentExclusions":{"type":"object","additionalProperties":false,"description":"Creators never put in the segment. Replaced as a whole on update.","properties":{"creators":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CreatorRef"},"description":"Read back as creator ids."},"list_ids":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"The members of these lists (of this workspace). Read when the segment is committed and at each paid renewal, not every day."},"exclude_disqualified":{"type":"boolean","default":true,"description":"Leave out the creators the key's owner disqualified."}}},"SegmentInputsProcessing":{"type":"object","properties":{"status":{"type":"string","enum":["seeds_processing","brands_processing","creators_processing"]},"retry_after":{"type":"integer","example":20},"seeds":{"type":"array","description":"`seeds_processing`: the rule's lookalike seeds.","items":{"$ref":"#/components/schemas/SegmentInputRow"}},"brands":{"type":"array","description":"`brands_processing`: the rule's Radar brands.","items":{"$ref":"#/components/schemas/SegmentInputRow"}},"creators":{"type":"array","description":"`creators_processing`: the creators in `exclusions.creators`.","items":{"$ref":"#/components/schemas/SegmentInputRow"}}}},"SegmentInputRow":{"type":"object","properties":{"index":{"type":"integer"},"input":{"$ref":"#/components/schemas/CreatorRef"},"creator_id":{"type":"string","nullable":true},"status":{"type":"string","enum":["ready","processing"]}}},"SegmentCount":{"type":"object","properties":{"size":{"type":"integer","description":"Creators the stored rule matches now.","example":640},"is_approximate":{"type":"boolean","description":"true when `size` is an estimate (exclusions applied to a large match, or a capped candidate set)."},"size_limit":{"type":"integer","description":"The size the price is for.","example":640},"commit_cost":{"type":"integer","description":"What `POST /commit` charges at `size_limit` — send it as `confirm_cost`. 0 when already committed.","example":26},"recurring_cost":{"type":"integer","description":"Charged again every `billing_cycle_days` while active.","example":26},"billing_cycle_days":{"type":"integer","example":30}}},"SegmentDeleted":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["deleted"]},"list_id":{"type":"string","nullable":true,"description":"The segment's list, deleted with it (null when it had none)."}}},"Tracker":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused"]},"list_id":{"type":"string","nullable":true,"description":"The list whose creators are tracked."},"segment_id":{"type":"string","nullable":true,"description":"The segment that list belongs to, when tracking a segment."},"rank_enabled":{"type":"boolean"},"creator_count":{"type":"integer"},"last_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Last nightly update."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TrackerQuota":{"type":"object","description":"Distinct creators tracked this calendar month (UTC). A creator keeps its spot until `reset_at`, even if its tracker is paused or deleted.","properties":{"used":{"type":"integer","example":212},"limit":{"type":"integer","example":300},"remaining":{"type":"integer","example":88},"period_start":{"type":"string","format":"date-time"},"reset_at":{"type":"string","format":"date-time"}}},"TrackerCreatorStats":{"type":"object","description":"The creator's numbers over the period (the network's under `network`). null = no data for the period (the app shows \"-\").","properties":{"authority":{"type":"number","nullable":true,"description":"Authority score at the end of the period."},"followers":{"type":"integer","nullable":true,"description":"Followers at the end of the period."},"followers_evolution":{"type":"integer","nullable":true,"description":"Followers gained (or lost) over the period."},"growth":{"type":"number","nullable":true,"description":"Follower growth over the period, in % (5.1 = +5.1%)."},"posts":{"type":"integer"},"engagement_rate":{"type":"number","nullable":true,"description":"Percentage (2.5 = 2.5%)."},"engagement_count":{"type":"integer","nullable":true},"views":{"type":"integer","nullable":true},"likes":{"type":"integer","nullable":true},"comments":{"type":"integer","nullable":true},"shares":{"type":"integer","nullable":true}}},"TrackerCreatorRow":{"allOf":[{"$ref":"#/components/schemas/CreatorCard"},{"type":"object","properties":{"rank":{"type":"integer","description":"Position in the leaderboard's order, over the whole tracker."},"stats":{"$ref":"#/components/schemas/TrackerCreatorStats"}}}]}},"examples":{"MissingApiKey":{"summary":"missing_api_key","value":{"error":{"code":"missing_api_key","message":"API key is required. Provide it via Authorization: Bearer <key> or X-API-Key header.","status":401,"details":[]}}},"InvalidApiKey":{"summary":"invalid_api_key","value":{"error":{"code":"invalid_api_key","message":"Invalid or revoked API key.","status":401,"details":[]}}},"KeyNotScoped":{"summary":"key_not_scoped","value":{"error":{"code":"key_not_scoped","message":"This API key is not scoped to a workspace. Please regenerate it from your workspace settings.","status":401,"details":[]}}},"ApiAccessDisabled":{"summary":"api_access_disabled","value":{"error":{"code":"api_access_disabled","message":"This workspace does not have Public API access. The API is available as an add-on — contact your Favikon representative to enable it.","status":403,"details":[]}}},"UserBanned":{"summary":"user_banned","value":{"error":{"code":"user_banned","message":"Your account has been suspended.","status":403,"details":[]}}},"AccountPendingDeletion":{"summary":"account_pending_deletion","value":{"error":{"code":"account_pending_deletion","message":"The account that owns this API key is scheduled for deletion.","status":403,"details":[]}}},"ApiDiscoveryDisabled":{"summary":"api_discovery_disabled","value":{"error":{"code":"api_discovery_disabled","message":"This workspace does not have the API Discovery add-on. Contact your Favikon representative to enable it.","status":403,"details":[]}}},"InvalidParameters":{"summary":"invalid_parameters","value":{"error":{"code":"invalid_parameters","message":"`per_page` must be 100 or fewer.","status":422,"details":[{"field":"per_page","reason":"`per_page` must be 100 or fewer."}]}}},"InvalidCursor":{"summary":"invalid_cursor","value":{"error":{"code":"invalid_cursor","message":"`cursor` is not a cursor issued by this API.","status":422,"details":[]}}},"SearchNotFound":{"summary":"search_not_found","value":{"error":{"code":"search_not_found","message":"This search doesn't exist or doesn't belong to this workspace. Run it again.","status":404,"details":[]}}},"SearchExpired":{"summary":"search_expired","value":{"error":{"code":"search_expired","message":"This search has expired (searches are kept for 24 hours). Run it again.","status":410,"details":[]}}},"RateLimitExceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"Rate limit exceeded. Maximum 20 requests per 2 seconds.","status":429,"details":[]}}},"SearchRateLimitExceeded":{"summary":"rate_limit_exceeded","value":{"error":{"code":"rate_limit_exceeded","message":"Rate limit exceeded. Searches count as 5 requests. Maximum 20 requests per 2 seconds.","status":429,"details":[]}}},"DailyResultLimit":{"summary":"daily_result_limit","value":{"error":{"code":"daily_result_limit","message":"This workspace has used 10,000 of its 10,000 Discovery results for today (UTC). The quota resets at midnight UTC.","status":429,"details":[{"field":"usage","reason":"daily_result_limit","results_today":10000,"daily_limit":10000}]}}},"SearchResultLimit":{"summary":"search_result_limit","value":{"error":{"code":"search_result_limit","message":"A search returns at most 1,000 results. Narrow the search to reach other results.","status":429,"details":[]}}},"InternalError":{"summary":"internal_error","value":{"error":{"code":"internal_error","message":"Something went wrong on our side. Please retry.","status":500,"details":[]}}},"AuthenticationError":{"summary":"authentication_error","value":{"error":{"code":"authentication_error","message":"An error occurred during authentication.","status":500,"details":[]}}},"SearchUnavailable":{"summary":"search_unavailable","value":{"error":{"code":"search_unavailable","message":"Search is temporarily unavailable. Retry in a few seconds.","status":503,"details":[]}}},"SearchBusy":{"summary":"search_busy","value":{"error":{"code":"search_busy","message":"Search is at capacity right now. Retry in a couple of seconds; nothing was charged.","status":503,"details":[]}}},"KeyOwnerNotMember":{"summary":"key_owner_not_member","value":{"error":{"code":"key_owner_not_member","message":"The owner of this API key is no longer an active member of its workspace. Ask a workspace owner or admin for a new key.","status":403,"details":[]}}},"KeyOwnerNotAdmin":{"summary":"key_owner_not_admin","value":{"error":{"code":"key_owner_not_admin","message":"The owner of this API key is no longer an owner or admin of its workspace. Ask a workspace owner or admin for a new key.","status":403,"details":[]}}},"PagePending":{"summary":"page_pending","value":{"error":{"code":"page_pending","message":"This page is being fetched by another request. Retry in a couple of seconds; nothing was charged.","status":503,"details":[]}}},"IngestLimitReached":{"summary":"ingest_limit_reached","value":{"error":{"code":"ingest_limit_reached","message":"This workspace has fetched its daily maximum of new creators from the networks. Creators already in Favikon still work; new ones can be fetched again after midnight UTC.","status":429,"details":[{"field":"seeds[1]","reason":"This workspace has fetched 500 new creators from the networks today, the daily maximum. Creators already in Favikon can still be added; new ones can be fetched again after midnight UTC.","code":"ingest_limit_reached"}]}}},"IngestUnavailable":{"summary":"ingest_unavailable","value":{"error":{"code":"ingest_unavailable","message":"Creator lookup is temporarily unavailable. Retry in a few seconds.","status":503,"details":[{"field":"seeds[1]","reason":"Creator lookup is temporarily unavailable. Retry in a moment.","code":"ingest_unavailable"}]}}},"SeedAnalysisLimitReached":{"summary":"seed_analysis_limit_reached","value":{"error":{"code":"seed_analysis_limit_reached","message":"This workspace has started its daily maximum of 100 seed analyses. Seeds already analysed still work; new ones can be analysed again after midnight UTC.","status":429,"details":[{"field":"seeds[1]","reason":"This seed needs an analysis the daily maximum no longer covers."}]}}},"CreatorCard":{"summary":"A creator card","value":{"creator_id":"656c43ab0c36863cb1ca11c5","name":"Julien Moreau","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/656c43ab0c36863cb1ca11c5.jpg?X-Amz-Expires=604800&X-Amz-Signature=3f1c…","profile_url":"https://app.favikon.com/profile/656c43ab0c36863cb1ca11c5","is_brand":false,"social_links":[{"platform":"linkedin","username":"julien-moreau","url":"https://www.linkedin.com/in/julien-moreau","verified":false,"followers":48200,"engagement_rate":2.5},{"platform":"x","username":"julienmoreau","url":"https://x.com/julienmoreau","verified":false,"followers":6100,"engagement_rate":0.8}],"score":8120,"tier":2,"followers":54300,"language":"fr","gender":"male","country":"FR","age":38,"job_title":"Founder & CEO","company":"Pipelane","description":"Building Pipelane, a CRM for B2B sales teams. I write about growth, pricing and hiring.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d0e1","name":"Business"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d0f2","name":"Startups","is_primary":true},{"id":"64f1b2c3d4e5f6a7b8c9d0f3","name":"Sales","is_primary":false}],"associated_brands":[{"creator_id":"5f8e9d0c1b2a3f4e5d6c7b8a","name":"Pipelane"}]}},"SecondCreatorCard":{"summary":"Another creator card","value":{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}]}},"BrandCard":{"summary":"A brand card","value":{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/60a1b2c3d4e5f6a7b8c9d0aa.jpg?X-Amz-Expires=604800&X-Amz-Signature=c41d…","profile_url":"https://app.favikon.com/profile/60a1b2c3d4e5f6a7b8c9d0aa","is_brand":true,"social_links":[{"platform":"instagram","username":"lumeaparis","url":"https://www.instagram.com/lumeaparis","verified":true,"followers":412000,"engagement_rate":1.2}],"score":8640,"tier":2,"followers":412000,"language":"fr","gender":null,"country":"FR","age":null,"job_title":null,"company":null,"description":"Clean skincare, made in Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[]}},"CreatorSearchPage":{"summary":"A page of creators","value":{"data":[{"creator_id":"656c43ab0c36863cb1ca11c5","name":"Julien Moreau","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/656c43ab0c36863cb1ca11c5.jpg?X-Amz-Expires=604800&X-Amz-Signature=3f1c…","profile_url":"https://app.favikon.com/profile/656c43ab0c36863cb1ca11c5","is_brand":false,"social_links":[{"platform":"linkedin","username":"julien-moreau","url":"https://www.linkedin.com/in/julien-moreau","verified":false,"followers":48200,"engagement_rate":2.5},{"platform":"x","username":"julienmoreau","url":"https://x.com/julienmoreau","verified":false,"followers":6100,"engagement_rate":0.8}],"score":8120,"tier":2,"followers":54300,"language":"fr","gender":"male","country":"FR","age":38,"job_title":"Founder & CEO","company":"Pipelane","description":"Building Pipelane, a CRM for B2B sales teams. I write about growth, pricing and hiring.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d0e1","name":"Business"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d0f2","name":"Startups","is_primary":true},{"id":"64f1b2c3d4e5f6a7b8c9d0f3","name":"Sales","is_primary":false}],"associated_brands":[{"creator_id":"5f8e9d0c1b2a3f4e5d6c7b8a","name":"Pipelane"}],"in_crm":false,"match_score":92},{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}],"in_crm":true,"match_score":87}],"meta":{"api_version":"v1","credits":{"remaining":485,"cost":2},"usage":{"results_today":300,"daily_limit":10000},"pagination":{"page":1,"page_size":50,"total":312,"has_more":true,"next_cursor":"eyJ2IjozLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwidyI6IjNmOWExYzBiN2UyZCJ9.l8y8yBU6p7WhA0I2PLQTwA"}}}},"ContentSearchPage":{"summary":"A page of posts","value":{"data":[{"post_id":"instagram_3215546789012345678","platform":"instagram","url":"https://www.instagram.com/p/C8xYz12AbCd/","published_at":"2026-09-14T17:32:00.000Z","format":"reel","content_type":"short_video","caption":"My 3-step skincare routine for sensitive skin ✨ no fragrance, no fuss.","thumbnail_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/thumbnails/instagram_3215546789012345678.jpg?X-Amz-Expires=604800&X-Amz-Signature=5b0e…","views":248000,"likes":18400,"comments":412,"shares":1250,"engagement_rate":7.6,"is_sponsored":false,"creator":{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}]}}],"meta":{"api_version":"v1","credits":{"remaining":486,"cost":1},"usage":{"results_today":325,"daily_limit":10000},"pagination":{"page":1,"page_size":25,"total":null,"has_more":true,"next_cursor":"eyJ2IjozLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwidyI6IjNmOWExYzBiN2UyZCJ9.l8y8yBU6p7WhA0I2PLQTwA"}}}},"CreatorRankingsPage":{"summary":"A creators board","value":{"data":[{"creator_id":"656c43ab0c36863cb1ca11c5","name":"Julien Moreau","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/656c43ab0c36863cb1ca11c5.jpg?X-Amz-Expires=604800&X-Amz-Signature=3f1c…","profile_url":"https://app.favikon.com/profile/656c43ab0c36863cb1ca11c5","is_brand":false,"social_links":[{"platform":"linkedin","username":"julien-moreau","url":"https://www.linkedin.com/in/julien-moreau","verified":false,"followers":48200,"engagement_rate":2.5},{"platform":"x","username":"julienmoreau","url":"https://x.com/julienmoreau","verified":false,"followers":6100,"engagement_rate":0.8}],"score":8120,"tier":2,"followers":54300,"language":"fr","gender":"male","country":"FR","age":38,"job_title":"Founder & CEO","company":"Pipelane","description":"Building Pipelane, a CRM for B2B sales teams. I write about growth, pricing and hiring.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d0e1","name":"Business"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d0f2","name":"Startups","is_primary":true},{"id":"64f1b2c3d4e5f6a7b8c9d0f3","name":"Sales","is_primary":false}],"associated_brands":[{"creator_id":"5f8e9d0c1b2a3f4e5d6c7b8a","name":"Pipelane"}],"in_crm":false,"rank":1,"ranking_score":8120},{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}],"in_crm":true,"rank":2,"ranking_score":7450}],"meta":{"api_version":"v1","credits":{"remaining":486,"cost":1},"usage":{"results_today":350,"daily_limit":10000},"type":"creators","top_id":"tech_all-niches_all-social-medias_france_all-genders","page":1,"per_page":25,"total":200,"total_pages":8}}},"BrandRankingsPage":{"summary":"A brands board","value":{"data":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/60a1b2c3d4e5f6a7b8c9d0aa.jpg?X-Amz-Expires=604800&X-Amz-Signature=c41d…","profile_url":"https://app.favikon.com/profile/60a1b2c3d4e5f6a7b8c9d0aa","is_brand":true,"social_links":[{"platform":"instagram","username":"lumeaparis","url":"https://www.instagram.com/lumeaparis","verified":true,"followers":412000,"engagement_rate":1.2}],"score":8640,"tier":2,"followers":412000,"language":"fr","gender":null,"country":"FR","age":null,"job_title":null,"company":null,"description":"Clean skincare, made in Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[],"in_crm":false,"rank":1,"ranking_score":8640}],"meta":{"api_version":"v1","credits":{"remaining":485,"cost":1},"usage":{"results_today":375,"daily_limit":10000},"type":"brands","top_id":"tech_all-niches_all-social-medias_france","page":1,"per_page":25,"total":200,"total_pages":8}}},"TaxonomyFilters":{"summary":"The taxonomy (shortened)","value":{"data":{"industries":[{"id":"64f1b2c3d4e5f6a7b8c9d0e5","name":"Food & Drink","slug":"food-drink","niches":[{"id":"64f1b2c3d4e5f6a7b8c9d0e6","name":"Home Cooking","slug":"home-cooking"},{"id":"64f1b2c3d4e5f6a7b8c9d0e7","name":"Vegan","slug":"vegan"}]}],"brand_industries":[{"id":"64f1b2c3d4e5f6a7b8c9d1b0","name":"Beauty & Personal Care","slug":"beauty-personal-care","niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1b1","name":"Skincare","slug":"skincare"}]}]},"meta":{"api_version":"v1"}}},"LocationFilters":{"summary":"The locations (shortened)","value":{"data":{"continents":[{"code":"eu","slug":"europe","name":"Europe","countries":[{"code":"BE","slug":"belgium","name":"Belgium"},{"code":"FR","slug":"france","name":"France"},{"code":"DE","slug":"germany","name":"Germany"}]},{"code":"na","slug":"north-america","name":"North America","countries":[{"code":"CA","slug":"canada","name":"Canada"},{"code":"US","slug":"united-states","name":"United States"}]}],"groups":[{"slug":"worldwide-english","name":"English speaking"},{"slug":"worldwide-french","name":"French speaking"},{"slug":"quebec","name":"Quebec"}],"languages":[{"code":"en","name":"English"},{"code":"fr","name":"French"},{"code":"de","name":"German"}]},"meta":{"api_version":"v1"}}},"OptionFilters":{"summary":"Every option and limit","value":{"data":{"platforms":["instagram","tiktok","youtube","linkedin","x"],"genders":["male","female","all"],"profile_types":["creators","brands","all"],"tiers":[1,2,3,4,5,6,7,8,9,10],"platform_stats_metrics":["followers","growth","engagement_rate","engagement_per_post","views_per_post","post_frequency"],"creator_search":{"sorts":["relevance","authority","followers","growth","engagement","views"],"default_per_page":25,"max_per_page":100},"content_search":{"sorts":["relevance","recent","views","engagement","engagement_rate","likes","comments","shares"],"modes":["hybrid","semantic","keyword"],"operators":["and","or"],"content_types":["short_video","long_video","image","carousel","text"],"metrics":["views","likes","comments","shares","engagement","engagement_rate"],"max_keywords":10,"max_exclude_keywords":10,"page_size":25},"rankings":{"networks":["instagram","tiktok","youtube","linkedin","x"],"genders":["male","female","other"],"default_per_page":25,"max_per_page":100,"max_rows":200},"limits":{"max_results_per_search":1000,"search_ttl_hours":24,"daily_results":10000}},"meta":{"api_version":"v1"}}},"SearchCreator":{"summary":"A search result card","value":{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","title":"Skincare for sensitive skin","country_code":"FR","tier":3,"profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","platforms":[{"platform":"instagram","followers":182000,"engagement_rate":3.4,"profile_url":"https://www.instagram.com/sarah.glow"},{"platform":"tiktok","followers":95400,"engagement_rate":6.1,"profile_url":"https://www.tiktok.com/@sarahglow"}],"in_crm":false}},"SecondSearchCreator":{"summary":"Another search result card","value":{"creator_id":"61d4c3b2a1f0e9d8c7b6a5f4","name":"Inès Garnier","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/61d4c3b2a1f0e9d8c7b6a5f4.jpg?X-Amz-Expires=604800&X-Amz-Signature=02bd…","title":"Clean beauty & everyday make-up","country_code":"BE","tier":4,"profile_url":"https://app.favikon.com/profile/61d4c3b2a1f0e9d8c7b6a5f4","platforms":[{"platform":"instagram","followers":64300,"engagement_rate":4.2,"profile_url":"https://www.instagram.com/ines.garnier"}],"in_crm":true}},"LookalikePage":{"summary":"A page of lookalikes","value":{"data":[{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","title":"Skincare for sensitive skin","country_code":"FR","tier":3,"profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","platforms":[{"platform":"instagram","followers":182000,"engagement_rate":3.4,"profile_url":"https://www.instagram.com/sarah.glow"},{"platform":"tiktok","followers":95400,"engagement_rate":6.1,"profile_url":"https://www.tiktok.com/@sarahglow"}],"in_crm":false,"match_score":87},{"creator_id":"61d4c3b2a1f0e9d8c7b6a5f4","name":"Inès Garnier","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/61d4c3b2a1f0e9d8c7b6a5f4.jpg?X-Amz-Expires=604800&X-Amz-Signature=02bd…","title":"Clean beauty & everyday make-up","country_code":"BE","tier":4,"profile_url":"https://app.favikon.com/profile/61d4c3b2a1f0e9d8c7b6a5f4","platforms":[{"platform":"instagram","followers":64300,"engagement_rate":4.2,"profile_url":"https://www.instagram.com/ines.garnier"}],"in_crm":true,"match_score":81}],"meta":{"api_version":"v1","credits":{"remaining":484,"cost":2},"pagination":{"page":1,"page_size":25,"total":1000,"has_more":true,"next_cursor":"eyJ2IjoyLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwiaCI6IjZKV194YldVYzVZelpYWXYweGNsckEifQ"}}}},"SeedsProcessing":{"summary":"A seed is still being fetched","value":{"data":{"status":"seeds_processing","retry_after":20,"seeds":[{"index":0,"input":"63a477561c819689ff4e32f8","creator_id":"63a477561c819689ff4e32f8","status":"ready"},{"index":1,"input":{"instagramHandle":"bianca.d"},"creator_id":null,"status":"processing"}]},"meta":{"api_version":"v1","credits":{"remaining":486,"cost":0}}}},"RadarSearchPage":{"summary":"A page of creators who mention the brand","value":{"data":{"radar_search_id":"66f3a8ed4b1e2c3d4e5f6a7b","brands":[{"creator_id":"5d2c1b0a9f8e7d6c5b4a3f2e","name":"Nike","tracked_platforms":["instagram","tiktok","x"]}],"creators":[{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","title":"Skincare for sensitive skin","country_code":"FR","tier":3,"profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","platforms":[{"platform":"instagram","followers":182000,"engagement_rate":3.4,"profile_url":"https://www.instagram.com/sarah.glow"},{"platform":"tiktok","followers":95400,"engagement_rate":6.1,"profile_url":"https://www.tiktok.com/@sarahglow"}],"in_crm":false,"mention_count":12},{"creator_id":"61d4c3b2a1f0e9d8c7b6a5f4","name":"Inès Garnier","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/61d4c3b2a1f0e9d8c7b6a5f4.jpg?X-Amz-Expires=604800&X-Amz-Signature=02bd…","title":"Clean beauty & everyday make-up","country_code":"BE","tier":4,"profile_url":"https://app.favikon.com/profile/61d4c3b2a1f0e9d8c7b6a5f4","platforms":[{"platform":"instagram","followers":64300,"engagement_rate":4.2,"profile_url":"https://www.instagram.com/ines.garnier"}],"in_crm":true,"mention_count":7}]},"meta":{"api_version":"v1","credits":{"remaining":484,"cost":2},"usage":{"results_today":275,"daily_limit":10000},"pagination":{"page":1,"page_size":50,"total":87,"has_more":true,"next_cursor":"eyJ2IjoyLCJzIjoiNjZmM2E4ZWQ0YjFlMmMzZDRlNWY2YTdiIiwicCI6MiwiaCI6IjZKV194YldVYzVZelpYWXYweGNsckEifQ"}}}},"BrandsProcessing":{"summary":"A brand is still being fetched","value":{"data":{"status":"brands_processing","retry_after":20,"brands":[{"index":0,"input":{"instagramHandle":"nike"},"creator_id":null,"status":"processing"}]},"meta":{"api_version":"v1","credits":{"remaining":486,"cost":0}}}},"RadarCreatorPostsPage":{"summary":"The posts behind a mention count","value":{"data":[{"post_id":"instagram_3221478563214789654","platform":"instagram","url":"https://www.instagram.com/p/C9aBc34DeFg/","published_at":"2026-09-02T09:15:00.000Z","format":"reel","caption":"Morning run in the new kicks 👟 @nike #ad","thumbnail_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/thumbnails/instagram_3221478563214789654.jpg?X-Amz-Expires=604800&X-Amz-Signature=77c2…","views":96500,"likes":7300,"comments":184,"shares":210,"engagement_rate":4.2,"is_brand_partnership":true,"tagged_brand":{"creator_id":"5d2c1b0a9f8e7d6c5b4a3f2e","name":"Nike","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/5d2c1b0a9f8e7d6c5b4a3f2e.jpg?X-Amz-Expires=604800&X-Amz-Signature=e019…"}}],"meta":{"api_version":"v1","radar_search_id":"66f3a8ed4b1e2c3d4e5f6a7b","creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","mention_count":12,"page":1,"per_page":20,"total":12,"total_pages":1,"credits":{"remaining":484,"cost":0}}}},"EnrichmentData":{"summary":"An enriched creator profile","value":{"creator_id":"63a477561c819689ff4e32f8","name":"Bianca Durand","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/63a477561c819689ff4e32f8.jpg?X-Amz-Expires=604800&X-Amz-Signature=a1f0…","country":"FR","language":"fr","age":27,"gender":"female","job_title":"Content creator","company":null,"email":"hello@biancadurand.example","email_status":"found","handles":{"instagram":"bianca.d","tiktok":"biancadurand","x":"biancad"},"scores":{"global":7310,"per_network":{"instagram":7480,"tiktok":6920,"x":3150},"authenticity":{"x":{"overall":82.5,"followers":88.1,"engagement":79.4,"content":84,"ai_content":4.2,"expertise":61.3}}},"stats":{"instagram":{"followers":214000,"follower_growth":1.8,"engagement":6420,"engagement_rate":3,"total_posts_last_90d":41,"post_price_estimate":2400,"avg_posts_per_month":13.7,"avg_posts_per_week":3.2,"avg_views":58000,"avg_likes":6150,"avg_comments":270,"avg_shares":95},"tiktok":{"followers":132500,"follower_growth":3.4,"engagement":9100,"engagement_rate":6.9,"total_posts_last_90d":28,"post_price_estimate":1600,"avg_posts_per_month":9.3,"avg_posts_per_week":2.2,"avg_views":104000,"avg_likes":8700,"avg_comments":210,"avg_shares":190}},"insights":{"description":"Lifestyle and slow-fashion creator based in Lyon: thrifted outfits, plant-based recipes and weekend trips.","brand_safety":94,"tone":"Warm and conversational","positivity":{"label":"Very positive","level":0.86},"collab_openness":"Open to collaborations"},"topics":["slow fashion","thrifting","plant-based recipes","weekend trips"],"niches":["Fashion","Sustainable Living","Home Cooking"],"audience":{"instagram":{"top_countries":[{"country":"FR","percentage":71.4},{"country":"BE","percentage":8.2}],"top_cities":[{"city":"Lyon","percentage":14.6},{"city":"Paris","percentage":12.9}],"top_languages":[{"language":"fr","percentage":83.1},{"language":"en","percentage":9.7}],"gender_split":{"male":18.4,"female":81.6}}},"partnered_brands":[{"name":"Maison Verte","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/brand-maison-verte.jpg?X-Amz-Expires=604800&X-Amz-Signature=5c3d…","occurrences":4}],"last_refreshed_at":"2026-10-04T08:12:00.000Z","last_enriched_at":"2026-10-05T14:03:12.000Z"}},"EnrichmentDataLive":{"summary":"An enriched creator profile, with its live ratings and ranks","value":{"creator_id":"63a477561c819689ff4e32f8","name":"Bianca Durand","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/63a477561c819689ff4e32f8.jpg?X-Amz-Expires=604800&X-Amz-Signature=a1f0…","country":"FR","language":"fr","age":27,"gender":"female","job_title":"Content creator","company":null,"email":"hello@biancadurand.example","email_status":"found","handles":{"instagram":"bianca.d","tiktok":"biancadurand","x":"biancad"},"scores":{"global":7310,"per_network":{"instagram":7480,"tiktok":6920,"x":3150},"authenticity":{"x":{"overall":82.5,"followers":88.1,"engagement":79.4,"content":84,"ai_content":4.2,"expertise":61.3}}},"stats":{"instagram":{"followers":214000,"follower_growth":1.8,"engagement":6420,"engagement_rate":3,"total_posts_last_90d":41,"post_price_estimate":2400,"avg_posts_per_month":13.7,"avg_posts_per_week":3.2,"avg_views":58000,"avg_likes":6150,"avg_comments":270,"avg_shares":95,"ratings":{"period":"last_year","computed_at":"2026-10-05T14:03:05.000Z","engagement_rate":{"rating":"good","label":"Good","value":2.71,"peer_median":2.4},"engagement":{"rating":"excellent","label":"Excellent","value":5800,"peer_median":4650},"follower_growth":{"rating":"good","label":"Good","value":12.6,"peer_median":null},"posting":{"rating":"good","label":"Good","value":11.5,"peer_median":10.4,"unit":"month"}}},"tiktok":{"followers":132500,"follower_growth":3.4,"engagement":9100,"engagement_rate":6.9,"total_posts_last_90d":28,"post_price_estimate":1600,"avg_posts_per_month":9.3,"avg_posts_per_week":2.2,"avg_views":104000,"avg_likes":8700,"avg_comments":210,"avg_shares":190,"ratings":{"period":"last_year","computed_at":"2026-10-05T14:03:05.000Z","engagement_rate":{"rating":"below_average","label":"Below Average","value":5.1,"peer_median":6.8},"engagement":{"rating":"average","label":"Average","value":7900,"peer_median":8100},"follower_growth":{"rating":"excellent","label":"Excellent","value":34.2,"peer_median":null},"posting":null}}},"insights":{"description":"Lifestyle and slow-fashion creator based in Lyon: thrifted outfits, plant-based recipes and weekend trips.","brand_safety":94,"brand_safety_label":"Very Safe","tone":"Warm and conversational","positivity":{"label":"Very positive","level":0.86},"collab_openness":"Open to collaborations"},"topics":["slow fashion","thrifting","plant-based recipes","weekend trips"],"niches":["Fashion","Sustainable Living","Home Cooking"],"audience":{"instagram":{"top_countries":[{"country":"FR","percentage":71.4},{"country":"BE","percentage":8.2}],"top_cities":[{"city":"Lyon","percentage":14.6},{"city":"Paris","percentage":12.9}],"top_languages":[{"language":"fr","percentage":83.1},{"language":"en","percentage":9.7}],"gender_split":{"male":18.4,"female":81.6}}},"partnered_brands":[{"name":"Maison Verte","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/brand-maison-verte.jpg?X-Amz-Expires=604800&X-Amz-Signature=5c3d…","occurrences":4}],"last_refreshed_at":"2026-10-04T08:12:00.000Z","last_enriched_at":"2026-10-05T14:03:12.000Z","rankings":[{"rank":38,"board_size":1912,"top_percent":2,"board":{"top_id":"fashion-beauty_fashion-beauty-lifestyle_instagram_france","network":"instagram","country":{"code":"FR","name":"France"},"language":null,"industry":"Fashion & Beauty","niche":"Fashion & Beauty Lifestyle","gender":null}},{"rank":412,"board_size":9870,"top_percent":4,"board":{"top_id":"fashion-beauty_all-niches_all-social-medias_france","network":null,"country":{"code":"FR","name":"France"},"language":null,"industry":"Fashion & Beauty","niche":null,"gender":null}},{"rank":5210,"board_size":61400,"top_percent":8,"board":{"top_id":"all-categories_all-niches_tiktok_france","network":"tiktok","country":{"code":"FR","name":"France"},"language":null,"industry":null,"niche":null,"gender":null}}]}},"EnrichmentPending":{"summary":"Enrichment started","value":{"data":{"enrichment_id":"6701a2b3c4d5e6f7a8b9c0d1","bulk_id":null,"status":"pending","input":{"network":"instagram","username":"bianca.d"},"creator_id":null,"data":null,"error":null,"created_at":"2026-10-05T14:02:40.000Z","completed_at":null},"meta":{"api_version":"v1","credits":{"remaining":487,"cost":3}}}},"EnrichmentDone":{"summary":"Enrichment done","value":{"data":{"enrichment_id":"6701a2b3c4d5e6f7a8b9c0d1","bulk_id":null,"status":"done","input":{"network":"instagram","username":"bianca.d"},"creator_id":"63a477561c819689ff4e32f8","data":{"creator_id":"63a477561c819689ff4e32f8","name":"Bianca Durand","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/63a477561c819689ff4e32f8.jpg?X-Amz-Expires=604800&X-Amz-Signature=a1f0…","country":"FR","language":"fr","age":27,"gender":"female","job_title":"Content creator","company":null,"email":"hello@biancadurand.example","email_status":"found","handles":{"instagram":"bianca.d","tiktok":"biancadurand","x":"biancad"},"scores":{"global":7310,"per_network":{"instagram":7480,"tiktok":6920,"x":3150},"authenticity":{"x":{"overall":82.5,"followers":88.1,"engagement":79.4,"content":84,"ai_content":4.2,"expertise":61.3}}},"stats":{"instagram":{"followers":214000,"follower_growth":1.8,"engagement":6420,"engagement_rate":3,"total_posts_last_90d":41,"post_price_estimate":2400,"avg_posts_per_month":13.7,"avg_posts_per_week":3.2,"avg_views":58000,"avg_likes":6150,"avg_comments":270,"avg_shares":95,"ratings":{"period":"last_year","computed_at":"2026-10-05T14:03:05.000Z","engagement_rate":{"rating":"good","label":"Good","value":2.71,"peer_median":2.4},"engagement":{"rating":"excellent","label":"Excellent","value":5800,"peer_median":4650},"follower_growth":{"rating":"good","label":"Good","value":12.6,"peer_median":null},"posting":{"rating":"good","label":"Good","value":11.5,"peer_median":10.4,"unit":"month"}}},"tiktok":{"followers":132500,"follower_growth":3.4,"engagement":9100,"engagement_rate":6.9,"total_posts_last_90d":28,"post_price_estimate":1600,"avg_posts_per_month":9.3,"avg_posts_per_week":2.2,"avg_views":104000,"avg_likes":8700,"avg_comments":210,"avg_shares":190,"ratings":{"period":"last_year","computed_at":"2026-10-05T14:03:05.000Z","engagement_rate":{"rating":"below_average","label":"Below Average","value":5.1,"peer_median":6.8},"engagement":{"rating":"average","label":"Average","value":7900,"peer_median":8100},"follower_growth":{"rating":"excellent","label":"Excellent","value":34.2,"peer_median":null},"posting":null}}},"insights":{"description":"Lifestyle and slow-fashion creator based in Lyon: thrifted outfits, plant-based recipes and weekend trips.","brand_safety":94,"brand_safety_label":"Very Safe","tone":"Warm and conversational","positivity":{"label":"Very positive","level":0.86},"collab_openness":"Open to collaborations"},"topics":["slow fashion","thrifting","plant-based recipes","weekend trips"],"niches":["Fashion","Sustainable Living","Home Cooking"],"audience":{"instagram":{"top_countries":[{"country":"FR","percentage":71.4},{"country":"BE","percentage":8.2}],"top_cities":[{"city":"Lyon","percentage":14.6},{"city":"Paris","percentage":12.9}],"top_languages":[{"language":"fr","percentage":83.1},{"language":"en","percentage":9.7}],"gender_split":{"male":18.4,"female":81.6}}},"partnered_brands":[{"name":"Maison Verte","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/brand-maison-verte.jpg?X-Amz-Expires=604800&X-Amz-Signature=5c3d…","occurrences":4}],"last_refreshed_at":"2026-10-04T08:12:00.000Z","last_enriched_at":"2026-10-05T14:03:12.000Z","rankings":[{"rank":38,"board_size":1912,"top_percent":2,"board":{"top_id":"fashion-beauty_fashion-beauty-lifestyle_instagram_france","network":"instagram","country":{"code":"FR","name":"France"},"language":null,"industry":"Fashion & Beauty","niche":"Fashion & Beauty Lifestyle","gender":null}},{"rank":412,"board_size":9870,"top_percent":4,"board":{"top_id":"fashion-beauty_all-niches_all-social-medias_france","network":null,"country":{"code":"FR","name":"France"},"language":null,"industry":"Fashion & Beauty","niche":null,"gender":null}},{"rank":5210,"board_size":61400,"top_percent":8,"board":{"top_id":"all-categories_all-niches_tiktok_france","network":"tiktok","country":{"code":"FR","name":"France"},"language":null,"industry":null,"niche":null,"gender":null}}]},"error":null,"created_at":"2026-10-05T14:02:40.000Z","completed_at":"2026-10-05T14:03:12.000Z"},"meta":{"api_version":"v1","credits":{"remaining":484,"cost":3},"ratings_status":"ready"}}},"EnrichBulkAccepted":{"summary":"Bulk accepted","value":{"data":{"bulk_id":"6701a2b3c4d5e6f7a8b9c0f0","enrichments":[{"index":0,"enrichment_id":"6701a2b3c4d5e6f7a8b9c0f1","status":"pending","input":{"network":"linkedin","username":"marc-richard"},"error":null},{"index":1,"enrichment_id":"6701a2b3c4d5e6f7a8b9c0f2","status":"pending","input":{"network":"instagram","username":"bianca.d"},"error":null},{"index":2,"enrichment_id":null,"status":"failed","input":{"network":null,"username":null},"error":{"code":"insufficient_credits","message":"Insufficient credits. Enriching this creator costs 3 credits."}}]},"meta":{"api_version":"v1","credits":{"remaining":2,"cost":6}}}},"EnrichBulkStatus":{"summary":"Bulk in progress","value":{"data":{"bulk_id":"6701a2b3c4d5e6f7a8b9c0f0","total":2,"all_complete":false,"summary":{"pending":1,"done":1,"failed":0},"enrichments":[{"enrichment_id":"6701a2b3c4d5e6f7a8b9c0f1","bulk_id":"6701a2b3c4d5e6f7a8b9c0f0","status":"pending","input":{"network":"linkedin","username":"marc-richard"},"creator_id":null,"data":null,"error":null,"created_at":"2026-10-05T14:02:40.000Z","completed_at":null},{"enrichment_id":"6701a2b3c4d5e6f7a8b9c0f2","bulk_id":"6701a2b3c4d5e6f7a8b9c0f0","status":"done","input":{"network":"instagram","username":"bianca.d"},"creator_id":"63a477561c819689ff4e32f8","data":{"creator_id":"63a477561c819689ff4e32f8","name":"Bianca Durand","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/63a477561c819689ff4e32f8.jpg?X-Amz-Expires=604800&X-Amz-Signature=a1f0…","country":"FR","language":"fr","age":27,"gender":"female","job_title":"Content creator","company":null,"email":"hello@biancadurand.example","email_status":"found","handles":{"instagram":"bianca.d","tiktok":"biancadurand","x":"biancad"},"scores":{"global":7310,"per_network":{"instagram":7480,"tiktok":6920,"x":3150},"authenticity":{"x":{"overall":82.5,"followers":88.1,"engagement":79.4,"content":84,"ai_content":4.2,"expertise":61.3}}},"stats":{"instagram":{"followers":214000,"follower_growth":1.8,"engagement":6420,"engagement_rate":3,"total_posts_last_90d":41,"post_price_estimate":2400,"avg_posts_per_month":13.7,"avg_posts_per_week":3.2,"avg_views":58000,"avg_likes":6150,"avg_comments":270,"avg_shares":95},"tiktok":{"followers":132500,"follower_growth":3.4,"engagement":9100,"engagement_rate":6.9,"total_posts_last_90d":28,"post_price_estimate":1600,"avg_posts_per_month":9.3,"avg_posts_per_week":2.2,"avg_views":104000,"avg_likes":8700,"avg_comments":210,"avg_shares":190}},"insights":{"description":"Lifestyle and slow-fashion creator based in Lyon: thrifted outfits, plant-based recipes and weekend trips.","brand_safety":94,"tone":"Warm and conversational","positivity":{"label":"Very positive","level":0.86},"collab_openness":"Open to collaborations"},"topics":["slow fashion","thrifting","plant-based recipes","weekend trips"],"niches":["Fashion","Sustainable Living","Home Cooking"],"audience":{"instagram":{"top_countries":[{"country":"FR","percentage":71.4},{"country":"BE","percentage":8.2}],"top_cities":[{"city":"Lyon","percentage":14.6},{"city":"Paris","percentage":12.9}],"top_languages":[{"language":"fr","percentage":83.1},{"language":"en","percentage":9.7}],"gender_split":{"male":18.4,"female":81.6}}},"partnered_brands":[{"name":"Maison Verte","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/brand-maison-verte.jpg?X-Amz-Expires=604800&X-Amz-Signature=5c3d…","occurrences":4}],"last_refreshed_at":"2026-10-04T08:12:00.000Z","last_enriched_at":"2026-10-05T14:03:12.000Z"},"error":null,"created_at":"2026-10-05T14:02:40.000Z","completed_at":"2026-10-05T14:03:12.000Z"}]},"meta":{"api_version":"v1","credits":{"remaining":2,"cost":3}}}},"CreatorRead":{"summary":"A live creator read","value":{"data":{"creator_id":"63a477561c819689ff4e32f8","name":"Bianca Durand","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/63a477561c819689ff4e32f8.jpg?X-Amz-Expires=604800&X-Amz-Signature=a1f0…","country":"FR","language":"fr","age":27,"gender":"female","job_title":"Content creator","company":null,"email":"hello@biancadurand.example","email_status":"found","handles":{"instagram":"bianca.d","tiktok":"biancadurand","x":"biancad"},"scores":{"global":7310,"per_network":{"instagram":7480,"tiktok":6920,"x":3150},"authenticity":{"x":{"overall":82.5,"followers":88.1,"engagement":79.4,"content":84,"ai_content":4.2,"expertise":61.3}}},"stats":{"instagram":{"followers":214000,"follower_growth":1.8,"engagement":6420,"engagement_rate":3,"total_posts_last_90d":41,"post_price_estimate":2400,"avg_posts_per_month":13.7,"avg_posts_per_week":3.2,"avg_views":58000,"avg_likes":6150,"avg_comments":270,"avg_shares":95,"ratings":{"period":"last_year","computed_at":"2026-10-05T14:03:05.000Z","engagement_rate":{"rating":"good","label":"Good","value":2.71,"peer_median":2.4},"engagement":{"rating":"excellent","label":"Excellent","value":5800,"peer_median":4650},"follower_growth":{"rating":"good","label":"Good","value":12.6,"peer_median":null},"posting":{"rating":"good","label":"Good","value":11.5,"peer_median":10.4,"unit":"month"}}},"tiktok":{"followers":132500,"follower_growth":3.4,"engagement":9100,"engagement_rate":6.9,"total_posts_last_90d":28,"post_price_estimate":1600,"avg_posts_per_month":9.3,"avg_posts_per_week":2.2,"avg_views":104000,"avg_likes":8700,"avg_comments":210,"avg_shares":190,"ratings":{"period":"last_year","computed_at":"2026-10-05T14:03:05.000Z","engagement_rate":{"rating":"below_average","label":"Below Average","value":5.1,"peer_median":6.8},"engagement":{"rating":"average","label":"Average","value":7900,"peer_median":8100},"follower_growth":{"rating":"excellent","label":"Excellent","value":34.2,"peer_median":null},"posting":null}}},"insights":{"description":"Lifestyle and slow-fashion creator based in Lyon: thrifted outfits, plant-based recipes and weekend trips.","brand_safety":94,"brand_safety_label":"Very Safe","tone":"Warm and conversational","positivity":{"label":"Very positive","level":0.86},"collab_openness":"Open to collaborations"},"topics":["slow fashion","thrifting","plant-based recipes","weekend trips"],"niches":["Fashion","Sustainable Living","Home Cooking"],"audience":{"instagram":{"top_countries":[{"country":"FR","percentage":71.4},{"country":"BE","percentage":8.2}],"top_cities":[{"city":"Lyon","percentage":14.6},{"city":"Paris","percentage":12.9}],"top_languages":[{"language":"fr","percentage":83.1},{"language":"en","percentage":9.7}],"gender_split":{"male":18.4,"female":81.6}}},"partnered_brands":[{"name":"Maison Verte","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/brand-maison-verte.jpg?X-Amz-Expires=604800&X-Amz-Signature=5c3d…","occurrences":4}],"last_refreshed_at":"2026-10-04T08:12:00.000Z","last_enriched_at":"2026-10-05T14:03:12.000Z","rankings":[{"rank":38,"board_size":1912,"top_percent":2,"board":{"top_id":"fashion-beauty_fashion-beauty-lifestyle_instagram_france","network":"instagram","country":{"code":"FR","name":"France"},"language":null,"industry":"Fashion & Beauty","niche":"Fashion & Beauty Lifestyle","gender":null}},{"rank":412,"board_size":9870,"top_percent":4,"board":{"top_id":"fashion-beauty_all-niches_all-social-medias_france","network":null,"country":{"code":"FR","name":"France"},"language":null,"industry":"Fashion & Beauty","niche":null,"gender":null}},{"rank":5210,"board_size":61400,"top_percent":8,"board":{"top_id":"all-categories_all-niches_tiktok_france","network":"tiktok","country":{"code":"FR","name":"France"},"language":null,"industry":null,"niche":null,"gender":null}}]},"meta":{"api_version":"v1","credits":{"remaining":484,"cost":0},"refresh_status":"fresh","ratings_status":"ready"}}},"ContactList":{"summary":"A list","value":{"list_id":"6702a1b2c3d4e5f6a7b8c901","name":"Fashion creators — Europe","contact_count":42,"created_at":"2026-09-12T10:04:00.000Z","updated_at":"2026-10-05T14:10:00.000Z"}},"ListsPage":{"summary":"The workspace's lists","value":{"data":[{"list_id":"6702a1b2c3d4e5f6a7b8c901","name":"Fashion creators — Europe","contact_count":42,"created_at":"2026-09-12T10:04:00.000Z","updated_at":"2026-10-05T14:10:00.000Z"},{"list_id":"6702a1b2c3d4e5f6a7b8c902","name":"SaaS founders — France","contact_count":18,"created_at":"2026-08-30T08:41:00.000Z","updated_at":"2026-09-28T16:22:00.000Z"}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":2,"total_pages":1}}},"ListCreated":{"summary":"List created","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","name":"Fashion creators — Europe","contact_count":0,"created_at":"2026-10-05T14:09:00.000Z","updated_at":"2026-10-05T14:09:00.000Z"},"meta":{"api_version":"v1"}}},"ListDeleted":{"summary":"List deleted","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","name":"Fashion creators — Europe","status":"deleted"},"meta":{"api_version":"v1"}}},"ListContactsPage":{"summary":"A page of the list's contacts","value":{"data":[{"contact_id":"6702a9c8d7e6f5a4b3c2d101","creator_id":"63a477561c819689ff4e32f8","name":"Bianca Durand","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/63a477561c819689ff4e32f8.jpg?X-Amz-Expires=604800&X-Amz-Signature=a1f0…","country":"FR","job_title":"Content creator","company":null,"email":"hello@biancadurand.example","email_status":"found","followers_count":346500,"last_enriched_at":"2026-10-05T14:03:12.000Z","last_refreshed_at":"2026-10-04T08:12:00.000Z"},{"contact_id":"6702a9c8d7e6f5a4b3c2d102","creator_id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…","country":"FR","job_title":"Head of Growth","company":"Pipelane","email":null,"email_status":"searching","followers_count":12800,"last_enriched_at":null,"last_refreshed_at":"2026-09-30T11:45:00.000Z"}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":42,"total_pages":3}}},"ListContactsAdded":{"summary":"Every creator added","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"added":1,"already_in_list":0,"not_found":0,"failed":0},"contacts":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"contact_id":"6702a9c8d7e6f5a4b3c2d102","name":"Marc Richard","status":"added","error":null}],"contacts_added":[{"creator_id":"6524b53cfa6624efbeeef72a","contact_id":"6702a9c8d7e6f5a4b3c2d102"}]},"meta":{"api_version":"v1"}}},"ListContactsMixed":{"summary":"Mixed outcomes","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"added":1,"already_in_list":1,"not_found":0,"failed":0},"contacts":[{"creator_id":"63a477561c819689ff4e32f8","input_handle":{"instagramHandle":"bianca.d"},"contact_id":"6702a9c8d7e6f5a4b3c2d101","name":"Bianca Durand","status":"already_in_list","error":null},{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":{"linkedinHandle":"marc-richard"},"contact_id":"6702a9c8d7e6f5a4b3c2d102","name":"Marc Richard","status":"added","error":null}],"contacts_added":[{"creator_id":"6524b53cfa6624efbeeef72a","contact_id":"6702a9c8d7e6f5a4b3c2d102"}]},"meta":{"api_version":"v1"}}},"ListContactsAllFailed":{"summary":"Every creator failed","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"added":0,"already_in_list":0,"not_found":0,"failed":1},"contacts":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"contact_id":null,"name":"Marc Richard","status":"failed","error":{"code":"add_failed","message":"Failed to add contact."}}],"contacts_added":[]},"meta":{"api_version":"v1"}}},"ListContactsAllNotFound":{"summary":"Every creator unknown","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"added":0,"already_in_list":0,"not_found":1,"failed":0},"contacts":[{"creator_id":"69bb967146ae23484eb74d66","input_handle":null,"contact_id":null,"name":null,"status":"not_found","error":{"code":"creator_not_found","message":"Creator does not exist."}}],"contacts_added":[]},"meta":{"api_version":"v1"}}},"ListContactsAllPresent":{"summary":"Every creator already in the list","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"added":0,"already_in_list":1,"not_found":0,"failed":0},"contacts":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"contact_id":"6702a9c8d7e6f5a4b3c2d102","name":"Marc Richard","status":"already_in_list","error":null}],"contacts_added":[]},"meta":{"api_version":"v1"}}},"ListNotFound":{"summary":"not_found","value":{"error":{"code":"not_found","message":"List not found.","status":404,"details":[]}}},"ListContactsRemoved":{"summary":"Every creator removed","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"removed":1,"not_in_list":0,"not_found":0,"failed":0},"contacts":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"contact_id":"6702a9c8d7e6f5a4b3c2d102","name":"Marc Richard","status":"removed","error":null}]},"meta":{"api_version":"v1"}}},"ListContactsRemoveMixed":{"summary":"Mixed outcomes","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"removed":1,"not_in_list":1,"not_found":0,"failed":0},"contacts":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"contact_id":"6702a9c8d7e6f5a4b3c2d102","name":"Marc Richard","status":"removed","error":null},{"creator_id":"63a477561c819689ff4e32f8","input_handle":{"instagramHandle":"bianca.d"},"contact_id":null,"name":"Bianca Durand","status":"not_in_list","error":null}]},"meta":{"api_version":"v1"}}},"ListContactsRemoveAllFailed":{"summary":"Every removal failed","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"removed":0,"not_in_list":0,"not_found":0,"failed":1},"contacts":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"name":"Marc Richard","status":"failed","error":{"code":"unknown","message":"Unknown outcome."}}]},"meta":{"api_version":"v1"}}},"ListContactsRemoveAllNotFound":{"summary":"Every creator unknown","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","summary":{"removed":0,"not_in_list":0,"not_found":1,"failed":0},"contacts":[{"creator_id":null,"input_handle":{"tiktokHandle":"@unknown.creator"},"contact_id":null,"name":null,"status":"not_found","error":{"code":"creator_not_found","message":"No indexed creator for tiktok handle \"unknown.creator\"."}}]},"meta":{"api_version":"v1"}}},"ListContactRemoved":{"summary":"Creator removed","value":{"data":{"list_id":"6702a1b2c3d4e5f6a7b8c901","creator_id":"6524b53cfa6624efbeeef72a","contact_id":"6702a9c8d7e6f5a4b3c2d102","name":"Marc Richard","status":"removed"},"meta":{"api_version":"v1"}}},"CampaignCreator":{"summary":"A campaign creator","value":{"creator_id":"6524b53cfa6624efbeeef72a","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…","status":"contacted","automations":[{"channels":["email"],"status":"sent","date":"2026-09-20T09:00:00.000Z"}],"post_count":2,"platforms":["linkedin"],"price":{"amount":1200,"currency":"EUR"},"formats":["post"],"post_date":"2026-10-01T08:00:00.000Z","shipping_status":null,"payment_status":"pending","payment_condition":"On publication","payment_date":null,"email":"marc@pipelane.example","enriched_at":"2026-09-18T15:30:00.000Z","socials":{"instagram":null,"linkedin":{"handle":"marc-richard","url":"https://www.linkedin.com/in/marc-richard"},"tiktok":null,"youtube":null,"x":null},"score":6840,"tier":4,"followers":12800,"language":"fr","gender":"male","country":"FR","job_title":"Head of Growth","company":"Pipelane","industries":["Business"],"niches":["Sales","Startups"],"growth":2.4,"custom_properties":{"agency":"Direct"}}},"CampaignCreatorsPage":{"summary":"A page of the campaign's creators","value":{"data":[{"creator_id":"6524b53cfa6624efbeeef72a","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…","status":"contacted","automations":[{"channels":["email"],"status":"sent","date":"2026-09-20T09:00:00.000Z"}],"post_count":2,"platforms":["linkedin"],"price":{"amount":1200,"currency":"EUR"},"formats":["post"],"post_date":"2026-10-01T08:00:00.000Z","shipping_status":null,"payment_status":"pending","payment_condition":"On publication","payment_date":null,"email":"marc@pipelane.example","enriched_at":"2026-09-18T15:30:00.000Z","socials":{"instagram":null,"linkedin":{"handle":"marc-richard","url":"https://www.linkedin.com/in/marc-richard"},"tiktok":null,"youtube":null,"x":null},"score":6840,"tier":4,"followers":12800,"language":"fr","gender":"male","country":"FR","job_title":"Head of Growth","company":"Pipelane","industries":["Business"],"niches":["Sales","Startups"],"growth":2.4,"custom_properties":{"agency":"Direct"}}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":1,"total_pages":1}}},"CampaignCreatorsAdded":{"summary":"Every creator added","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","summary":{"added":2,"already_in_campaign":0,"not_found":0,"failed":0},"creators":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"name":"Marc Richard","status":"added","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","step_status_slug":"new","added_at":"2026-10-05T14:20:00.000Z","error":null},{"creator_id":"69bb967146ae23484eb74d66","input_handle":null,"name":"Claire Dubois","status":"added","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e102","step_status_slug":"new","added_at":"2026-10-05T14:20:00.000Z","error":null}],"contacts_added":[{"creator_id":"69bb967146ae23484eb74d66","contact_id":"6702a9c8d7e6f5a4b3c2d103"}]},"meta":{"api_version":"v1"}}},"CampaignCreatorsMixed":{"summary":"Mixed outcomes","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","summary":{"added":1,"already_in_campaign":1,"not_found":0,"failed":0},"creators":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":{"linkedinHandle":"marc-richard"},"name":"Marc Richard","status":"already_in_campaign","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","step_status_slug":"contacted","added_at":"2026-09-18T15:30:00.000Z","error":null},{"creator_id":"63a477561c819689ff4e32f8","input_handle":{"instagramHandle":"bianca.d"},"name":"Bianca Durand","status":"added","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e103","step_status_slug":"new","added_at":"2026-10-05T14:20:00.000Z","error":null}],"contacts_added":[]},"meta":{"api_version":"v1"}}},"CampaignCreatorsAllFailed":{"summary":"Every creator failed","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","summary":{"added":0,"already_in_campaign":0,"not_found":0,"failed":1},"creators":[{"creator_id":"6524b53cfa6624efbeeef72a","input_handle":null,"name":"Marc Richard","status":"failed","custom_creator_campaign_id":null,"step_status_slug":null,"added_at":null,"error":{"code":"add_failed","message":"Failed to add creator to campaign."}}],"contacts_added":[]},"meta":{"api_version":"v1"}}},"CampaignCreatorsRemoved":{"summary":"Every creator removed","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","summary":{"removed":2,"not_in_campaign":0,"not_found":0,"failed":0},"creators":[{"creator_id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","status":"removed","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","error":null},{"creator_id":"69bb967146ae23484eb74d66","name":"Claire Dubois","status":"removed","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e102","error":null}]},"meta":{"api_version":"v1"}}},"CampaignCreatorsRemoveMixed":{"summary":"Mixed outcomes","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","summary":{"removed":1,"not_in_campaign":1,"not_found":0,"failed":0},"creators":[{"creator_id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","status":"removed","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","error":null},{"creator_id":"69bb967146ae23484eb74d66","name":"Claire Dubois","status":"not_in_campaign","custom_creator_campaign_id":null,"error":null}]},"meta":{"api_version":"v1"}}},"CampaignCreatorsRemoveAllFailed":{"summary":"Every removal failed","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","summary":{"removed":0,"not_in_campaign":0,"not_found":0,"failed":1},"creators":[{"creator_id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","status":"failed","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101","error":{"code":"remove_failed","message":"Failed to remove creator from campaign."}}]},"meta":{"api_version":"v1"}}},"CampaignCreatorRemoved":{"summary":"Creator removed","value":{"data":{"campaign_id":"6702b2c3d4e5f6a7b8c9d0e1","creator_id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","status":"removed","custom_creator_campaign_id":"6702c3d4e5f6a7b8c9d0e101"},"meta":{"api_version":"v1"}}},"CampaignCreatorsAnalyticsPage":{"summary":"Per-creator results","value":{"data":[{"creator_id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…","metrics":{"posts":2,"engagement":1840,"engagement_rate":4.1,"views":45200,"emv":3150.5,"cpm":26.55,"cpe":0.65,"cpv":0.03,"website_visits":312,"conversion_events":null},"cost":{"budget":1200,"budget_engaged":1200}}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":1,"total_pages":1}}},"CampaignPost":{"summary":"A campaign post","value":{"post_id":"6702d4e5f6a7b8c9d0e1f201","platform":"linkedin","status":"approved","post_url":"https://www.linkedin.com/feed/update/urn:li:activity:7245891234567890123/","published_at":"2026-10-01T08:00:00.000Z","creator":{"id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…"},"content_preview":"We cut our sales cycle by 30% this quarter. Here is the pipeline review we now run every Monday…","media_type":"post","hashtags":["sales","b2b"],"mentions":["pipelane"],"metrics":{"views":31800,"engagement":1260,"likes":1104,"comments":96,"shares":60,"engagement_rate":3.96,"emv":2210.4}}},"CampaignPostsPage":{"summary":"A page of the campaign's posts","value":{"data":[{"post_id":"6702d4e5f6a7b8c9d0e1f201","platform":"linkedin","status":"approved","post_url":"https://www.linkedin.com/feed/update/urn:li:activity:7245891234567890123/","published_at":"2026-10-01T08:00:00.000Z","creator":{"id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…"},"content_preview":"We cut our sales cycle by 30% this quarter. Here is the pipeline review we now run every Monday…","media_type":"post","hashtags":["sales","b2b"],"mentions":["pipelane"],"metrics":{"views":31800,"engagement":1260,"likes":1104,"comments":96,"shares":60,"engagement_rate":3.96,"emv":2210.4}}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":1,"total_pages":1}}},"CampaignPostDetail":{"summary":"One post, with its full content","value":{"data":{"post_id":"6702d4e5f6a7b8c9d0e1f201","platform":"linkedin","status":"approved","post_url":"https://www.linkedin.com/feed/update/urn:li:activity:7245891234567890123/","published_at":"2026-10-01T08:00:00.000Z","creator":{"id":"6524b53cfa6624efbeeef72a","name":"Marc Richard","avatar_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/6524b53cfa6624efbeeef72a.jpg?X-Amz-Expires=604800&X-Amz-Signature=40aa…"},"content_preview":"We cut our sales cycle by 30% this quarter. Here is the pipeline review we now run every Monday…","media_type":"post","hashtags":["sales","b2b"],"mentions":["pipelane"],"metrics":{"views":31800,"engagement":1260,"likes":1104,"comments":96,"shares":60,"engagement_rate":3.96,"emv":2210.4},"content":"We cut our sales cycle by 30% this quarter. Here is the pipeline review we now run every Monday — 4 questions, 20 minutes, no slides.","media_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/medias/6702d4e5f6a7b8c9d0e1f201.jpg?X-Amz-Expires=604800&X-Amz-Signature=8e11…"},"meta":{"api_version":"v1"}}},"SegmentDraft":{"summary":"A draft segment","value":{"data":{"id":"6703a1b2c3d4e5f6a7b8c9d0","name":"FR running creators","status":"draft","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"creators":[],"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"],"exclude_disqualified":true},"size_limit":null,"member_count":null,"list_id":null,"cost":null,"committed_at":null,"next_charge_at":null,"charge_failed_at":null,"refreshed_at":null,"created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-05T14:30:00.000Z"},"meta":{"api_version":"v1"}}},"SegmentActive":{"summary":"A committed segment","value":{"data":{"id":"6703a1b2c3d4e5f6a7b8c9d0","name":"FR running creators","status":"active","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"creators":[],"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"],"exclude_disqualified":true},"size_limit":200,"member_count":187,"list_id":"6703b1c2d3e4f5a6b7c8d9e0","cost":8,"committed_at":"2026-10-05T14:41:00.000Z","next_charge_at":"2026-11-04T14:41:00.000Z","charge_failed_at":null,"refreshed_at":"2026-10-05T14:42:10.000Z","created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-05T14:41:00.000Z"},"meta":{"api_version":"v1"}}},"SegmentsPage":{"summary":"The workspace's segments","value":{"data":[{"id":"6703a1b2c3d4e5f6a7b8c9d0","name":"FR running creators","status":"active","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"creators":[],"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"],"exclude_disqualified":true},"size_limit":200,"member_count":187,"list_id":"6703b1c2d3e4f5a6b7c8d9e0","cost":8,"committed_at":"2026-10-05T14:41:00.000Z","next_charge_at":"2026-11-04T14:41:00.000Z","charge_failed_at":null,"refreshed_at":"2026-10-05T14:42:10.000Z","created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-05T14:41:00.000Z"},{"id":"6703a1b2c3d4e5f6a7b8c9d1","name":"Like our ambassadors","status":"draft","rule":{"source":"lookalikes","seeds":["63a477561c819689ff4e32f8","62b5e1f0a9c8d7e6f5a4b3c2"]},"exclusions":{"creators":[],"list_ids":[],"exclude_disqualified":true},"size_limit":null,"member_count":null,"list_id":null,"cost":null,"committed_at":null,"next_charge_at":null,"charge_failed_at":null,"refreshed_at":null,"created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-05T14:30:00.000Z"}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":2,"total_pages":1}}},"SegmentSeedsProcessing":{"summary":"A seed is still being fetched","value":{"data":{"status":"seeds_processing","retry_after":20,"seeds":[{"index":0,"input":"63a477561c819689ff4e32f8","creator_id":"63a477561c819689ff4e32f8","status":"ready"},{"index":1,"input":{"instagramHandle":"bianca.d"},"creator_id":null,"status":"processing"}]},"meta":{"api_version":"v1","credits":{"remaining":486,"cost":0}}}},"SegmentDeleted":{"summary":"Segment deleted","value":{"data":{"id":"6703a1b2c3d4e5f6a7b8c9d0","status":"deleted","list_id":"6703b1c2d3e4f5a6b7c8d9e0"},"meta":{"api_version":"v1"}}},"SegmentCount":{"summary":"The price of committing 200 creators","value":{"data":{"size":312,"is_approximate":false,"size_limit":200,"commit_cost":8,"recurring_cost":8,"billing_cycle_days":30},"meta":{"api_version":"v1","credits":{"remaining":486,"cost":0}}}},"SegmentCommitted":{"summary":"Segment committed","value":{"data":{"id":"6703a1b2c3d4e5f6a7b8c9d0","name":"FR running creators","status":"active","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"creators":[],"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"],"exclude_disqualified":true},"size_limit":200,"member_count":187,"list_id":"6703b1c2d3e4f5a6b7c8d9e0","cost":8,"committed_at":"2026-10-05T14:41:00.000Z","next_charge_at":"2026-11-04T14:41:00.000Z","charge_failed_at":null,"refreshed_at":"2026-10-05T14:42:10.000Z","created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-05T14:41:00.000Z"},"meta":{"api_version":"v1","credits":{"remaining":478,"cost":8},"already_committed":false}}},"SegmentPaused":{"summary":"Segment paused","value":{"data":{"id":"6703a1b2c3d4e5f6a7b8c9d0","name":"FR running creators","status":"paused","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"creators":[],"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"],"exclude_disqualified":true},"size_limit":200,"member_count":187,"list_id":"6703b1c2d3e4f5a6b7c8d9e0","cost":8,"committed_at":"2026-10-05T14:41:00.000Z","next_charge_at":"2026-11-04T14:41:00.000Z","charge_failed_at":null,"refreshed_at":"2026-10-05T14:42:10.000Z","created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-06T09:00:00.000Z"},"meta":{"api_version":"v1","credits":{"remaining":478,"cost":0}}}},"SegmentResumed":{"summary":"Segment resumed inside its paid period","value":{"data":{"id":"6703a1b2c3d4e5f6a7b8c9d0","name":"FR running creators","status":"active","rule":{"source":"creator_search","prompt":"trail running and marathon creators","filters":{"countries":["FR"],"platforms":["instagram","tiktok"]}},"exclusions":{"creators":[],"list_ids":["66f3a8ed4b1e2c3d4e5f6a7b"],"exclude_disqualified":true},"size_limit":200,"member_count":187,"list_id":"6703b1c2d3e4f5a6b7c8d9e0","cost":8,"committed_at":"2026-10-05T14:41:00.000Z","next_charge_at":"2026-11-04T14:41:00.000Z","charge_failed_at":null,"refreshed_at":"2026-10-05T14:42:10.000Z","created_at":"2026-10-05T14:30:00.000Z","updated_at":"2026-10-07T09:00:00.000Z"},"meta":{"api_version":"v1","credits":{"remaining":478,"cost":0}}}},"SegmentCreatorsPage":{"summary":"A page of the segment's creators","value":{"data":[{"creator_id":"656c43ab0c36863cb1ca11c5","name":"Julien Moreau","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/656c43ab0c36863cb1ca11c5.jpg?X-Amz-Expires=604800&X-Amz-Signature=3f1c…","profile_url":"https://app.favikon.com/profile/656c43ab0c36863cb1ca11c5","is_brand":false,"social_links":[{"platform":"linkedin","username":"julien-moreau","url":"https://www.linkedin.com/in/julien-moreau","verified":false,"followers":48200,"engagement_rate":2.5},{"platform":"x","username":"julienmoreau","url":"https://x.com/julienmoreau","verified":false,"followers":6100,"engagement_rate":0.8}],"score":8120,"tier":2,"followers":54300,"language":"fr","gender":"male","country":"FR","age":38,"job_title":"Founder & CEO","company":"Pipelane","description":"Building Pipelane, a CRM for B2B sales teams. I write about growth, pricing and hiring.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d0e1","name":"Business"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d0f2","name":"Startups","is_primary":true},{"id":"64f1b2c3d4e5f6a7b8c9d0f3","name":"Sales","is_primary":false}],"associated_brands":[{"creator_id":"5f8e9d0c1b2a3f4e5d6c7b8a","name":"Pipelane"}]},{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}]}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":187,"total_pages":10}}},"Tracker":{"summary":"A tracker","value":{"data":{"id":"6703c1d2e3f4a5b6c7d8e9f0","name":"Running creators — weekly","status":"active","list_id":"6703b1c2d3e4f5a6b7c8d9e0","segment_id":"6703a1b2c3d4e5f6a7b8c9d0","rank_enabled":true,"creator_count":187,"last_updated_at":"2026-10-05T18:00:00.000Z","created_at":"2026-10-05T14:50:00.000Z","updated_at":"2026-10-05T14:50:00.000Z"},"meta":{"api_version":"v1"}}},"TrackersPage":{"summary":"The workspace's trackers, and this month's quota","value":{"data":[{"id":"6703c1d2e3f4a5b6c7d8e9f0","name":"Running creators — weekly","status":"active","list_id":"6703b1c2d3e4f5a6b7c8d9e0","segment_id":"6703a1b2c3d4e5f6a7b8c9d0","rank_enabled":true,"creator_count":187,"last_updated_at":"2026-10-05T18:00:00.000Z","created_at":"2026-10-05T14:50:00.000Z","updated_at":"2026-10-05T14:50:00.000Z"}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":1,"total_pages":1,"quota":{"used":187,"limit":300,"remaining":113,"period_start":"2026-10-01T00:00:00.000Z","reset_at":"2026-11-01T00:00:00.000Z"}}}},"TrackerCreated":{"summary":"Tracker created","value":{"data":{"id":"6703c1d2e3f4a5b6c7d8e9f0","name":"Running creators — weekly","status":"active","list_id":"6703b1c2d3e4f5a6b7c8d9e0","segment_id":"6703a1b2c3d4e5f6a7b8c9d0","rank_enabled":true,"creator_count":187,"last_updated_at":null,"created_at":"2026-10-05T14:50:00.000Z","updated_at":"2026-10-05T14:50:00.000Z"},"meta":{"api_version":"v1","quota":{"used":187,"limit":300,"remaining":113,"period_start":"2026-10-01T00:00:00.000Z","reset_at":"2026-11-01T00:00:00.000Z"}}}},"TrackerDeleted":{"summary":"Tracker deleted","value":{"data":{"id":"6703c1d2e3f4a5b6c7d8e9f0","status":"deleted"},"meta":{"api_version":"v1"}}},"TrackerPaused":{"summary":"Tracker paused","value":{"data":{"id":"6703c1d2e3f4a5b6c7d8e9f0","name":"Running creators — weekly","status":"paused","list_id":"6703b1c2d3e4f5a6b7c8d9e0","segment_id":"6703a1b2c3d4e5f6a7b8c9d0","rank_enabled":true,"creator_count":187,"last_updated_at":"2026-10-05T18:00:00.000Z","created_at":"2026-10-05T14:50:00.000Z","updated_at":"2026-10-06T09:00:00.000Z"},"meta":{"api_version":"v1"}}},"TrackerCreatorsPage":{"summary":"The leaderboard","value":{"data":[{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}],"rank":1,"stats":{"authority":7450,"followers":277400,"followers_evolution":4200,"growth":1.5,"posts":14,"engagement_rate":4.6,"engagement_count":38900,"views":1240000,"likes":35800,"comments":1640,"shares":1460}},{"creator_id":"656c43ab0c36863cb1ca11c5","name":"Julien Moreau","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/656c43ab0c36863cb1ca11c5.jpg?X-Amz-Expires=604800&X-Amz-Signature=3f1c…","profile_url":"https://app.favikon.com/profile/656c43ab0c36863cb1ca11c5","is_brand":false,"social_links":[{"platform":"linkedin","username":"julien-moreau","url":"https://www.linkedin.com/in/julien-moreau","verified":false,"followers":48200,"engagement_rate":2.5},{"platform":"x","username":"julienmoreau","url":"https://x.com/julienmoreau","verified":false,"followers":6100,"engagement_rate":0.8}],"score":8120,"tier":2,"followers":54300,"language":"fr","gender":"male","country":"FR","age":38,"job_title":"Founder & CEO","company":"Pipelane","description":"Building Pipelane, a CRM for B2B sales teams. I write about growth, pricing and hiring.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d0e1","name":"Business"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d0f2","name":"Startups","is_primary":true},{"id":"64f1b2c3d4e5f6a7b8c9d0f3","name":"Sales","is_primary":false}],"associated_brands":[{"creator_id":"5f8e9d0c1b2a3f4e5d6c7b8a","name":"Pipelane"}],"rank":2,"stats":{"authority":8120,"followers":54300,"followers_evolution":900,"growth":1.7,"posts":9,"engagement_rate":2.3,"engagement_count":6100,"views":152000,"likes":5400,"comments":520,"shares":180}}],"meta":{"api_version":"v1","page":1,"per_page":20,"total":187,"total_pages":10,"start_date":"2026-07-08T00:00:00.000Z","end_date":"2026-10-05T23:59:59.999Z","network":"all","tracker_creator_count":187}}},"TrackerPostsPage":{"summary":"The posts feed","value":{"data":[{"post_id":"instagram_3215546789012345678","platform":"instagram","url":"https://www.instagram.com/p/C8xYz12AbCd/","published_at":"2026-09-14T17:32:00.000Z","format":"reel","content_type":"short_video","caption":"My 3-step skincare routine for sensitive skin ✨ no fragrance, no fuss.","thumbnail_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/thumbnails/instagram_3215546789012345678.jpg?X-Amz-Expires=604800&X-Amz-Signature=5b0e…","views":248000,"likes":18400,"comments":412,"shares":1250,"engagement_rate":7.6,"is_sponsored":false,"creator":{"creator_id":"62b5e1f0a9c8d7e6f5a4b3c2","name":"Sarah Lefèvre","picture_url":"https://favikon-medias.s3.eu-west-3.amazonaws.com/pictures/62b5e1f0a9c8d7e6f5a4b3c2.jpg?X-Amz-Expires=604800&X-Amz-Signature=9a7e…","profile_url":"https://app.favikon.com/profile/62b5e1f0a9c8d7e6f5a4b3c2","is_brand":false,"social_links":[{"platform":"instagram","username":"sarah.glow","url":"https://www.instagram.com/sarah.glow","verified":true,"followers":182000,"engagement_rate":3.4},{"platform":"tiktok","username":"sarahglow","url":"https://www.tiktok.com/@sarahglow","verified":false,"followers":95400,"engagement_rate":6.1}],"score":7450,"tier":3,"followers":277400,"language":"fr","gender":"female","country":"FR","age":29,"job_title":null,"company":null,"description":"Skincare routines for sensitive skin, tested for real. Paris.","industry":{"id":"64f1b2c3d4e5f6a7b8c9d1a0","name":"Beauty"},"niches":[{"id":"64f1b2c3d4e5f6a7b8c9d1a1","name":"Skincare","is_primary":true}],"associated_brands":[{"creator_id":"60a1b2c3d4e5f6a7b8c9d0aa","name":"Lumea Paris"}]}}],"meta":{"api_version":"v1","pagination":{"page":1,"page_size":25,"total":1462,"has_more":true,"next_cursor":"eyJ2IjoxLCJzIjoiNmFjM2MxNzAwNzQ5ZjQ0N2U5OTE2OWRlIiwidyI6IjJjYjNiNjFiNmU1MSIsInAiOjIsImEiOlsxNzI2MzM1MTIwMDAwLCJpbnN0YWdyYW1fMzIxNTU0Njc4OTAxMjM0NTY3OCJdfQ"},"start_date":"2026-07-08T00:00:00.000Z","end_date":"2026-10-05T23:59:59.999Z"}}}},"responses":{"Unauthorized":{"description":"- `missing_api_key` — no key in `Authorization: Bearer` or `X-API-Key`.\n- `invalid_api_key` — not a `fav_` key, revoked, or its workspace no longer exists.\n- `key_not_scoped` — a key minted before workspaces existed: regenerate it.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingApiKey":{"$ref":"#/components/examples/MissingApiKey"},"invalidApiKey":{"$ref":"#/components/examples/InvalidApiKey"},"keyNotScoped":{"$ref":"#/components/examples/KeyNotScoped"}}}}},"Forbidden":{"description":"- `api_access_disabled` — the workspace doesn't have the API add-on.\n- `user_banned` — the key's owner is suspended.\n- `account_pending_deletion` — the key's owner is scheduled for deletion.\n- `key_owner_not_member` — the key's owner is no longer an active member of its workspace (the key was revoked). Ask an owner or admin for a new key.\n- `key_owner_not_admin` — the key's owner is no longer an owner or admin of its workspace (the key was revoked). Ask an owner or admin for a new key.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"apiAccessDisabled":{"$ref":"#/components/examples/ApiAccessDisabled"},"userBanned":{"$ref":"#/components/examples/UserBanned"},"accountPendingDeletion":{"$ref":"#/components/examples/AccountPendingDeletion"},"keyOwnerNotMember":{"$ref":"#/components/examples/KeyOwnerNotMember"},"keyOwnerNotAdmin":{"$ref":"#/components/examples/KeyOwnerNotAdmin"}}}}},"ContactLimitForbidden":{"description":"- `workspace_contact_limit_reached` — the creators new to the workspace don't fit its contact limit, or nothing in the request could be added without room. Checked before anything is fetched; nothing was added. Upgrade the plan, or add fewer new creators.\n- `api_access_disabled` — the workspace doesn't have the API add-on.\n- `user_banned` — the key's owner is suspended.\n- `account_pending_deletion` — the key's owner is scheduled for deletion.\n- `key_owner_not_member` — the key's owner is no longer an active member of its workspace (the key was revoked). Ask an owner or admin for a new key.\n- `key_owner_not_admin` — the key's owner is no longer an owner or admin of its workspace (the key was revoked). Ask an owner or admin for a new key.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"workspaceContactLimitReached":{"summary":"workspace_contact_limit_reached","value":{"error":{"code":"workspace_contact_limit_reached","message":"Adding 12 contact(s) would exceed your 1000-contact limit (currently at 995). Upgrade your plan to add more.","status":403,"details":[]}}},"apiAccessDisabled":{"$ref":"#/components/examples/ApiAccessDisabled"},"userBanned":{"$ref":"#/components/examples/UserBanned"},"accountPendingDeletion":{"$ref":"#/components/examples/AccountPendingDeletion"},"keyOwnerNotMember":{"$ref":"#/components/examples/KeyOwnerNotMember"},"keyOwnerNotAdmin":{"$ref":"#/components/examples/KeyOwnerNotAdmin"}}}}},"DiscoveryForbidden":{"description":"- `api_discovery_disabled` — a Discovery API endpoint, and the workspace doesn't have the Discovery add-on.\n- `api_access_disabled` — the workspace doesn't have the API add-on.\n- `user_banned` — the key's owner is suspended.\n- `account_pending_deletion` — the key's owner is scheduled for deletion.\n- `key_owner_not_member` — the key's owner is no longer an active member of its workspace (the key was revoked). Ask an owner or admin for a new key.\n- `key_owner_not_admin` — the key's owner is no longer an owner or admin of its workspace (the key was revoked). Ask an owner or admin for a new key.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"apiDiscoveryDisabled":{"$ref":"#/components/examples/ApiDiscoveryDisabled"},"apiAccessDisabled":{"$ref":"#/components/examples/ApiAccessDisabled"},"userBanned":{"$ref":"#/components/examples/UserBanned"},"accountPendingDeletion":{"$ref":"#/components/examples/AccountPendingDeletion"},"keyOwnerNotMember":{"$ref":"#/components/examples/KeyOwnerNotMember"},"keyOwnerNotAdmin":{"$ref":"#/components/examples/KeyOwnerNotAdmin"}}}}},"InternalError":{"description":"- `internal_error` — an unexpected failure on our side. Retry; nothing was charged.\n- `authentication_error` — the key could not be checked. Retry.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internalError":{"$ref":"#/components/examples/InternalError"},"authenticationError":{"$ref":"#/components/examples/AuthenticationError"}}}}},"NotFound":{"description":"Resource not found (also returned for cross-workspace access attempts)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"Campaign not found.","status":404,"details":[]}}}}},"RateLimitExceeded":{"description":"`rate_limit_exceeded` — more than 20 units in the key's 2-second window (this call counts as 1). Wait `Retry-After` seconds.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key's window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimitExceeded":{"$ref":"#/components/examples/RateLimitExceeded"}}}}},"SearchRateLimitExceeded":{"description":"`rate_limit_exceeded` — more than 20 units in the key's 2-second window. This call counts as **5** (4 per 2 seconds). Wait `Retry-After` seconds.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the key's window resets."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimitExceeded":{"$ref":"#/components/examples/SearchRateLimitExceeded"}}}}},"InvalidParameters":{"description":"`invalid_parameters` — the request doesn't match the schema (unknown keys included). `details[]` has one entry per problem: `field` is the path, `reason` what's wrong.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidParameters":{"$ref":"#/components/examples/InvalidParameters"}}}}},"InsufficientCredits":{"description":"- `insufficient_credits` — the workspace can't cover what enriching this creator costs it: 3 credits, 2 with preview access, 0 inside the 30-day access window (a free enrichment is never refused). Nothing was charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficientCredits":{"summary":"insufficient_credits","value":{"error":{"code":"insufficient_credits","message":"Insufficient credits. Enriching this creator costs 3 credits.","status":402,"details":[]}}}}}}},"Conflict":{"description":"Resource collision — every item in a write request was already in\nthe target state. For single-item endpoints this means the resource\nalready exists; for bulk endpoints it means every input was a\nduplicate. The body still contains per-item details so the client\ncan distinguish.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"list_already_exists","message":"A list named \"Fashion creators — Europe\" already exists.","status":409,"details":[]}}}}},"EnrichmentExpired":{"description":"The enrichment result is older than 30 days and has been purged. Use the\nlong-lived `GET /api/v1/creators/{creator_id}` endpoint for the current\ndata (requires an active access window — a new enrich reopens one).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"enrichment_expired","message":"Enrichment result no longer available. Access current data via /creators/{creator_id}.","status":410,"details":[{"field":"creator_id","reason":"63a477561c819689ff4e32f8"}]}}}}},"SearchUnavailable":{"description":"`search_unavailable` — search is temporarily unavailable (a dependency is down). Nothing was charged — retry after `Retry-After` seconds.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchUnavailable":{"$ref":"#/components/examples/SearchUnavailable"}}}}},"SearchUnavailableOrBusy":{"description":"Nothing was charged or counted: retry after `Retry-After` seconds.\n\n- `search_busy` — the search engine is at its API-wide capacity (a cap on concurrent searches shared by every key), or this workspace already has a search of this kind running (one at a time per workspace). Refused at once, before any search ran.\n- `page_pending` — another request is fetching this very page right now. Retry after 2 seconds: the page is then served, free.\n- `search_unavailable` — search is temporarily unavailable (a dependency is down, or the search ran past its deadline).\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchBusy":{"$ref":"#/components/examples/SearchBusy"},"pagePending":{"$ref":"#/components/examples/PagePending"},"searchUnavailable":{"$ref":"#/components/examples/SearchUnavailable"}}}}},"CreatorRefSearchUnavailable":{"description":"Nothing was charged or counted: retry after `Retry-After` seconds.\n\n- `search_busy` — the search engine is at its API-wide capacity (a cap on concurrent searches shared by every key), or this workspace already has a search of this kind running (one at a time per workspace). Refused at once, before any search ran.\n- `page_pending` — another request is fetching this very page right now. Retry after 2 seconds: the page is then served, free.\n- `ingest_unavailable` — a creator passed by handle had to be fetched from its network, and creator lookup is briefly unavailable (`Retry-After: 5`). `details[].field` names each one.\n- `search_unavailable` — search is temporarily unavailable (a dependency is down, or the search ran past its deadline).\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchBusy":{"$ref":"#/components/examples/SearchBusy"},"pagePending":{"$ref":"#/components/examples/PagePending"},"ingestUnavailable":{"$ref":"#/components/examples/IngestUnavailable"},"searchUnavailable":{"$ref":"#/components/examples/SearchUnavailable"}}}}},"SearchNotFound":{"description":"`search_not_found` — the cursor points to a search that doesn't exist or belongs to another workspace. Run the search again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchNotFound":{"$ref":"#/components/examples/SearchNotFound"}}}}},"SearchExpired":{"description":"`search_expired` — the search is older than 24 hours. Run it again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchExpired":{"$ref":"#/components/examples/SearchExpired"}}}}},"SearchTooManyRequests":{"description":"- `daily_result_limit` — the page would take the workspace past its Discovery results for today (UTC); `Retry-After` counts down to midnight UTC. Nothing was charged.\n- `search_result_limit` — the cursor points past the 1,000th result of the search. Narrow the search instead.\n- `rate_limit_exceeded` — more than 20 units per 2 seconds (a search counts as 5).\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (rate limit, daily quota)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"dailyResultLimit":{"$ref":"#/components/examples/DailyResultLimit"},"searchResultLimit":{"$ref":"#/components/examples/SearchResultLimit"},"rateLimitExceeded":{"$ref":"#/components/examples/SearchRateLimitExceeded"}}}}},"SegmentInputsTooManyRequests":{"description":"- `rate_limit_exceeded` — more than 20 units in the key's 2-second window (this call counts as 1). Wait `Retry-After` seconds.\n- `ingest_limit_reached` — a creator passed by handle (a seed, a brand, an excluded creator) needs fetching from its network, and the workspace has fetched its 500 new creators for today. `details[].field` names each one; `Retry-After` counts down to midnight UTC. Nothing was saved.\n- `seed_analysis_limit_reached` — some lookalike seeds need an analysis, and the workspace has started its 100 seed analyses for today. `details[].field` names each seed; `Retry-After` counts down to midnight UTC. Nothing was saved.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (the key's window, or until midnight UTC)."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rateLimitExceeded":{"$ref":"#/components/examples/RateLimitExceeded"},"ingestLimitReached":{"summary":"ingest_limit_reached","value":{"error":{"code":"ingest_limit_reached","message":"This workspace has fetched its daily maximum of new creators from the networks. Creators already in Favikon still work; new ones can be fetched again after midnight UTC.","status":429,"details":[{"field":"rule.seeds[1]","reason":"This workspace has fetched 500 new creators from the networks today, the daily maximum. Creators already in Favikon can still be added; new ones can be fetched again after midnight UTC.","code":"ingest_limit_reached"}]}}},"seedAnalysisLimitReached":{"summary":"seed_analysis_limit_reached","value":{"error":{"code":"seed_analysis_limit_reached","message":"This workspace has started its daily maximum of 100 seed analyses. Seeds already analysed still work; new ones can be analysed again after midnight UTC.","status":429,"details":[{"field":"rule.seeds[1]","reason":"This seed needs an analysis the daily maximum no longer covers."}]}}}}}}},"SegmentInputsUnavailable":{"description":"Nothing was saved: retry after `Retry-After` seconds.\n\n- `ingest_unavailable` — a creator passed by handle had to be fetched from its network, and creator lookup is briefly unavailable (`Retry-After: 5`).\n- `search_unavailable` — lookalike seeds couldn't be checked right now (a dependency is down).\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ingestUnavailable":{"summary":"ingest_unavailable","value":{"error":{"code":"ingest_unavailable","message":"Creator lookup is temporarily unavailable. Retry in a few seconds.","status":503,"details":[{"field":"rule.brands[0]","reason":"Creator lookup is temporarily unavailable. Retry in a moment.","code":"ingest_unavailable"}]}}},"searchUnavailable":{"$ref":"#/components/examples/SearchUnavailable"}}}}},"RankingPage":{"description":"One page of the board.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RankingCreator"}},"meta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"usage":{"$ref":"#/components/schemas/SearchUsage"},"type":{"type":"string","enum":["creators","brands"]},"top_id":{"type":"string","description":"The board's id on favikon.com.","example":"tech_all-niches_all-social-medias_france_all-genders"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer","description":"Rows on the board (at most 200)."},"total_pages":{"type":"integer"}}}]}}},"examples":{"creatorsBoard":{"$ref":"#/components/examples/CreatorRankingsPage"},"brandsBoard":{"$ref":"#/components/examples/BrandRankingsPage"}}}}},"InvalidRankingSlug":{"description":"- `invalid_slug` — an unknown category, niche or location slug, a niche outside its category, or a gender on a brand board; `details[].field` names it.\n- `invalid_parameters` — the query doesn't match the schema (unknown parameters included, or a niche without its category).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_slug","message":"Unknown location \"atlantis\".","status":422,"details":[{"field":"location","reason":"Unknown location \"atlantis\"."}]}}}}},"CostMismatch":{"description":"- `cost_mismatch` — `confirm_cost` isn't the price of committing `size_limit` creators, or the segment's rule changed (`PATCH`) while this commit ran. **Nothing was charged**; `details[].expected` is the real price (also from `POST /count`).\n- `segment_rule_missing` — the draft has no usable rule yet.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"costMismatch":{"summary":"cost_mismatch","value":{"error":{"code":"cost_mismatch","message":"Committing 200 creators costs 8 credits, not 6. Nothing was charged.","status":409,"details":[{"field":"confirm_cost","reason":"cost_mismatch","expected":8,"received":6}]}}},"ruleChanged":{"summary":"cost_mismatch (rule changed)","value":{"error":{"code":"cost_mismatch","message":"The segment's rule changed while it was being committed. Nothing was charged: count it again (committing 200 creators now costs 12 credits).","status":409,"details":[{"field":"confirm_cost","reason":"cost_mismatch","expected":12,"received":8}]}}}}}}},"SegmentStateConflict":{"description":"- `segment_committed` — the rule or exclusions of a committed segment can't change.\n- `segment_not_committed` — a draft has no members and can't be paused or resumed: commit it first.\n- `segment_rule_missing` — the draft has no usable rule yet.\n- `seeds_not_ready` — lookalike seeds are still being analysed; retry after `Retry-After`.\n","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait (`seeds_not_ready` only)."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"segmentCommitted":{"summary":"segment_committed","value":{"error":{"code":"segment_committed","message":"The segment is committed: its rule can no longer change.","status":409,"details":[]}}},"segmentNotCommitted":{"summary":"segment_not_committed","value":{"error":{"code":"segment_not_committed","message":"The segment is a draft: commit it first (POST /segments/{id}/commit).","status":409,"details":[]}}},"segmentRuleMissing":{"summary":"segment_rule_missing","value":{"error":{"code":"segment_rule_missing","message":"The segment has no usable rule yet: set one with PATCH /segments/{id}.","status":409,"details":[]}}},"seedsNotReady":{"summary":"seeds_not_ready","value":{"error":{"code":"seeds_not_ready","message":"The lookalike seeds are still being analysed. Retry shortly.","status":409,"details":[]}}}}}}},"TrackerLimitReached":{"description":"`tracker_limit_reached` — the creators to track don't fit this month's quota. `details[0]` carries the quota (`used`, `limit`, `remaining`, `reset_at`) and `requested` (spots the tracker needs). Nothing was created.\n`segment_not_committed` — the segment is a draft.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"tracker_limit_reached","message":"Tracking these creators needs 120 more creator spots this month; 88 of 300 are left until 2026-11-01T00:00:00.000Z.","status":409,"details":[{"field":"quota","reason":"tracker_limit_reached","used":212,"limit":300,"remaining":88,"period_start":"2026-10-01T00:00:00.000Z","reset_at":"2026-11-01T00:00:00.000Z","requested":120}]}}}}},"TrackerPaused":{"description":"`tracker_paused` — resume the tracker to edit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"tracker_paused","message":"The tracker is paused: resume it to edit it.","status":409,"details":[]}}}}}}}}