{ "title": "UGC Agent API", "version": "2.2.0", "description": "Two ways in, one engine.\n\nPOST /v1/messages is the conversational surface: send a message, the agent\npicks its tools and answers with prose plus any creators it found.\n\nThe resource endpoints are for products that build on the engine directly,\nand they mirror the tabs of the web app:\n- Lists: persistent, appendable creator collections (`/v1/lists`).\n- Creator searches: background sourcing jobs with structured filters,\n partial results while running, and optional list targeting\n (`/v1/creator-searches`).\n- Webhooks: signed push of `lead.added` and job events (`/v1/webhooks`).\n- Automations: recurring lead sourcing into a list, or recurring trend\n research by email (`/v1/automations`).\n- Chats: list, rename, read and delete the chats in your web app sidebar\n (`/v1/chats`).\n- Creator CRM: every creator you saved, with pipeline stage, deal terms,\n notes, tasks and CRM lists (`/v1/leads`, `/v1/lead-lists`,\n `/v1/lead-exports`).\n- UGC Database: browse already-sourced creators and unlock them into the\n CRM (`/v1/database`).\n- UGC Brands: brands that run UGC creator programs, their attributed\n accounts, videos and playbook (`/v1/ugc-brands`).\n- Creator Tracking: tracked accounts, their videos, collections and\n payouts (`/v1/tracking`).\n- Applications: import, review and answer creator applications\n (`/v1/applications`).\n- Outreach integrations: push creators into Instantly or Smartlead\n campaigns (`/v1/integrations`).\n- Workspace: Agent Preferences, excluded creators and account usage\n (`/v1/preferences`, `/v1/account`).\n- Research jobs: creator account analyses, creator enrichments, brand\n research and trend research (`/v1/creator-analyses`,\n `/v1/creator-enrichments`, `/v1/brand-researches`,\n `/v1/trend-researches`).\n\nPlan gates mirror the app. When the workspace plan does not include \nfeature, the call answers 402 with error.code `upgrade_required` and\nerror.required_plan naming the lowest plan that unlocks it.\n\nThe typical integration: create a list, register a `lead.added` webhook on\nit, then start searches (or an automation) with `list_id` set. Every creator\nthat qualifies is appended to the list and pushed to the webhook as it\nlands, and later searches never return anyone already in the list.\n\nPOST /v1/messages runs a turn and waits for the result. A turn that outruns\nthe wait window answers 202 with a Location header; poll it with\nGET /v1/messages/{id} until stop_reason is no longer \"pending\".\n\nAPI access is available to Ultra and Enterprise workspaces, neither of\nwhich has a monthly credit ceiling. A turn that returns leads consumes\ncredits, which are metered per workspace and reported in\nAccount -> API -> Usage.\n\nUltra workspaces may make 100 job-creating calls per UTC day and 2,000 per\ncalendar month (UTC). Enterprise workspaces have no call caps. Premium\nworkspaces lost API access on 2026-09-08. Job-creating calls are:\nPOST /v1/messages, POST /v1/creator-searches, POST /v1/automations,\nPOST /v1/automations/{id}/runs, POST /v1/creator-analyses,\nPOST /v1/creator-enrichments, POST /v1/brand-researches,\nPOST /v1/trend-researches, POST /v1/application-reviews with\n`analyze_accounts: true`, and POST /v1/application-video-analyses. An\nidempotent replay or a call that fails before creating work is not\ncounted. Reads, polling and every other endpoint do not count against the\ncall quota (they are still rate limited per minute). Every job-creating\nresponse carries X-Quota-Daily-Limit, X-Quota-Daily-Remaining,\nX-Quota-Daily-Reset, X-Quota-Monthly-Limit, X-Quota-Monthly-Remaining and\nX-Quota-Monthly-Reset. An exhausted window answers 429 with error.code\napi_daily_quota_exceeded or api_monthly_quota_exceeded and a Retry-After\npointing at the reset. Enterprise workspaces have no call caps (the\nheaders read \"unlimited\").\n\nEvery response carries X-Request-Id; the same value is in error.request_id\non failures.\n\nTeam workspaces: every key addresses the workspace (the team owner's\nlead pool, call quota, lists, webhooks, automations, creator searches and\nresearch jobs). On per-person surfaces (Creator CRM, chats, outreach\nintegrations, Agent Preferences, applications, Creator Tracking) a key\nacts as the team member who created it, like that member in the app.\nKeys created before member attribution act as the workspace owner.\n\nIdempotency: mutations accept an Idempotency-Key header. A completed key\nreplays its result for 24 hours; a duplicate that arrives while the first\nrequest is still running answers 409 idempotency_in_progress with\nRetry-After; only successes and 400/422 validation errors are stored, so \n5xx, 402, 404, 409 or 429 releases the key for a retry. Automations keep\ntheir own receipt flow (a replay returns the stored automation or run).\n\nHosted MCP: the UGC Agent MCP server calls this same API on behalf of\nPremium, Ultra and Enterprise users. Metered job endpoints (POST\n/v1/messages, /v1/creator-searches, /v1/automations,\n/v1/automations/{id}/runs and the four research jobs) answer MCP callers\n403 not_available_on_mcp; MCP sourcing runs through its run_ugc_agent\ntool, which draws on the plan's lead pool like the app.", "groups": [ { "name": "Messages", "endpoints": [ { "id": "createMessage", "method": "POST", "path": "/v1/messages", "group": "Messages", "summary": "Send a message", "description": "Runs one agent turn. The agent picks its own tools from the request, so\nthe same endpoint serves creator search, brand research, account\nanalysis and enrichment. Any creators produced during the turn are\nreturned in the top-level `leads` array.\n\nCreator-search prompts accept negative constraints in plain language:\n\"any niche but photography\", \"any country except India\", \"no beauty\ncreators\", \"not US based\". Excluded verticals and markets are kept out\nof discovery and enforced as delivery gates; they are echoed back in\n`interpreted_request.excluded_niches` / `excluded_locations`.\n", "deprecated": false, "comingSoon": false, "params": [], "body": { "fields": [ { "name": "messages", "type": "object[]", "required": true, "description": "The conversation so far, oldest first. The final message must have\nrole \"user\" - that is the request the agent acts on. Earlier turns\nare context.\n", "constraints": [ "min 1 items", "max 50 items" ] }, { "name": "messages.role", "type": "enum", "required": true, "enum": [ "user", "assistant" ], "description": "Who sent the message.", "constraints": [] }, { "name": "messages.content", "type": "string", "required": true, "description": "The message text.", "constraints": [ "min length 1", "max length 5000" ] } ], "example": { "messages": [ { "role": "user", "content": "Find 20 skincare creators in Germany" } ] } }, "response": { "code": "200", "description": "The turn completed.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Message id, prefixed `msg_`.", "constraints": [] }, { "name": "type", "type": "enum", "required": false, "enum": [ "message" ], "description": "", "constraints": [] }, { "name": "role", "type": "enum", "required": false, "enum": [ "assistant" ], "description": "", "constraints": [] }, { "name": "content", "type": "object[]", "required": false, "description": "The assistant's prose. Empty while `stop_reason` is \"pending\".", "constraints": [] }, { "name": "content.type", "type": "enum", "required": false, "enum": [ "text" ], "description": "", "constraints": [] }, { "name": "content.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "leads", "type": "object[]", "required": false, "description": "Creators found during this turn. Always present; empty when none have\nbeen found yet. While `stop_reason` is \"pending\" this fills in\nprogressively, so polling shows partial results rather than nothing\nuntil the end.\n", "constraints": [] }, { "name": "leads.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "leads.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "leads.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "leads.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "leads.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "leads.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "leads.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "leads.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "leads.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "leads.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "leads.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "leads.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "leads.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "leads.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "leads.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "leads.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "leads.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "leads.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "leads.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "leads.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "leads.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "leads.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "leads.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "leads.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "stop_reason", "type": "enum", "required": false, "enum": [ "end_turn", "pending", "canceled", "error" ], "description": "`end_turn` when finished, `pending` while still running, `canceled`\nif stopped, `error` if the turn failed.\n", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits", "type": "integer", "required": false, "description": "Credits this turn consumed from the workspace's monthly pool.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "Populated only when `stop_reason` is \"error\".", "constraints": [] } ], "example": { "id": "msg_01H9Z2K4QW", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "I found 18 skincare creators in Germany with strong engagement." } ], "leads": [ { "handle": "hautliebe.mi", "platform": "instagram", "followers": 8400, "engagement_rate": 0.061, "email": "mia@hautliebe.de", "profile_url": "https://instagram.com/hautliebe.mi" } ], "stop_reason": "end_turn", "created_at": "2026-08-23T10:00:00.000Z", "usage": { "credits": 12 }, "error": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace credit pool is exhausted for this cycle." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." } ] }, { "id": "getMessage", "method": "GET", "path": "/v1/messages/{id}", "group": "Messages", "summary": "Retrieve a message", "description": "Returns a message by id, in the same shape POST returns. Only needed for\na turn that answered 202: poll until `stop_reason` is no longer\n\"pending\".\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "The message id returned by POST /v1/messages.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The message.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Message id, prefixed `msg_`.", "constraints": [] }, { "name": "type", "type": "enum", "required": false, "enum": [ "message" ], "description": "", "constraints": [] }, { "name": "role", "type": "enum", "required": false, "enum": [ "assistant" ], "description": "", "constraints": [] }, { "name": "content", "type": "object[]", "required": false, "description": "The assistant's prose. Empty while `stop_reason` is \"pending\".", "constraints": [] }, { "name": "content.type", "type": "enum", "required": false, "enum": [ "text" ], "description": "", "constraints": [] }, { "name": "content.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "leads", "type": "object[]", "required": false, "description": "Creators found during this turn. Always present; empty when none have\nbeen found yet. While `stop_reason` is \"pending\" this fills in\nprogressively, so polling shows partial results rather than nothing\nuntil the end.\n", "constraints": [] }, { "name": "leads.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "leads.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "leads.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "leads.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "leads.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "leads.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "leads.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "leads.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "leads.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "leads.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "leads.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "leads.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "leads.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "leads.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "leads.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "leads.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "leads.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "leads.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "leads.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "leads.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "leads.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "leads.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "leads.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "leads.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "stop_reason", "type": "enum", "required": false, "enum": [ "end_turn", "pending", "canceled", "error" ], "description": "`end_turn` when finished, `pending` while still running, `canceled`\nif stopped, `error` if the turn failed.\n", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits", "type": "integer", "required": false, "description": "Credits this turn consumed from the workspace's monthly pool.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "Populated only when `stop_reason` is \"error\".", "constraints": [] } ] }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] } ] }, { "name": "Lists", "endpoints": [ { "id": "listLists", "method": "GET", "path": "/v1/lists", "group": "Lists", "summary": "List lists", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "Lists, newest first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "creator_list" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "List id, prefixed list_.", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.last_job_id", "type": "string | null", "required": false, "description": "The most recent creator search or automation run that appended to the list.", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." } ] }, { "id": "createList", "method": "POST", "path": "/v1/lists", "group": "Lists", "summary": "Create a list", "description": "Creates an empty list. Send an `Idempotency-Key` to make the call safe\nto retry: the same key with the same body returns the original list\nwith `Idempotency-Replayed: true`; a different body answers 409.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "name", "type": "string", "required": true, "example": "Skincare US micro", "description": "Display name.", "constraints": [ "min length 1", "max length 120" ] }, { "name": "description", "type": "string | null", "required": false, "example": "Instantly campaign Q4", "description": "Free-text note shown with the list.", "constraints": [ "max length 1000" ] } ], "example": { "name": "Skincare US micro", "description": "Instantly campaign Q4" } }, "response": { "code": "200", "description": "Idempotent replay of an earlier create.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_list" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "List id, prefixed list_.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "last_job_id", "type": "string | null", "required": false, "description": "The most recent creator search or automation run that appended to the list.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getList", "method": "GET", "path": "/v1/lists/{id}", "group": "Lists", "summary": "Retrieve a list", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The list.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_list" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "List id, prefixed list_.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "last_job_id", "type": "string | null", "required": false, "description": "The most recent creator search or automation run that appended to the list.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "updateList", "method": "PATCH", "path": "/v1/lists/{id}", "group": "Lists", "summary": "Update a list", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": { "fields": [ { "name": "name", "type": "string", "required": false, "example": "Skincare US micro", "description": "Display name.", "constraints": [ "min length 1", "max length 120" ] }, { "name": "description", "type": "string | null", "required": false, "example": "Instantly campaign Q4", "description": "Free-text note shown with the list; null clears it.", "constraints": [ "max length 1000" ] } ] }, "response": { "code": "200", "description": "The updated list.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_list" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "List id, prefixed list_.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "last_job_id", "type": "string | null", "required": false, "description": "The most recent creator search or automation run that appended to the list.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "deleteList", "method": "DELETE", "path": "/v1/lists/{id}", "group": "Lists", "summary": "Delete a list", "description": "Deletes the list and its memberships. Creators themselves are not affected.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "listListLeads", "method": "GET", "path": "/v1/lists/{id}/leads", "group": "Lists", "summary": "List leads in a list", "description": "Members in the order they were added, so a consumer that stores the\nlast cursor can resume exactly where it stopped. Filters narrow the\npage; `added_after` is the cheapest way to poll for new members\nwithout webhooks.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "has_email", "in": "query", "required": false, "type": "boolean", "description": "", "constraints": [] }, { "name": "min_followers", "in": "query", "required": false, "type": "integer", "description": "", "constraints": [ "min 0" ] }, { "name": "max_followers", "in": "query", "required": false, "type": "integer", "description": "", "constraints": [ "min 0" ] }, { "name": "added_after", "in": "query", "required": false, "type": "string", "description": "Only members added strictly after this time.", "constraints": [] }, { "name": "source_id", "in": "query", "required": false, "type": "string", "description": "Only members added by this creator search or automation run.", "constraints": [] }, { "name": "q", "in": "query", "required": false, "type": "string", "description": "Case-insensitive match on handle, name, bio, niche or location.", "constraints": [ "max length 200" ] } ], "body": null, "response": { "code": "200", "description": "A page of leads.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "addListLeads", "method": "POST", "path": "/v1/lists/{id}/leads", "group": "Lists", "summary": "Add leads to a list", "description": "Appends creators. Membership is keyed by platform + handle, so adding \ncreator already in the list is a no-op counted in\n`skipped_duplicates`. Provide either `creators` (explicit rows) or\n`creator_search_id` (copy a completed search's results, optionally\nnarrowed with `creator_ids`). Each genuinely new member emits one\n`lead.added` webhook event.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": { "fields": [ { "name": "creators", "type": "object[]", "required": false, "description": "Creators to add. platform and handle identify the account; everything else is optional profile data.", "constraints": [ "min 1 items", "max 500 items" ] }, { "name": "creators.platform", "type": "enum", "required": true, "enum": [ "instagram", "tiktok" ], "example": "instagram", "description": "Where the account lives.", "constraints": [] }, { "name": "creators.handle", "type": "string", "required": true, "example": "hautliebe.mia", "description": "Username without the @.", "constraints": [] }, { "name": "creators.name", "type": "string", "required": false, "example": "Mia Hautliebe", "description": "Display name.", "constraints": [] }, { "name": "creators.email", "type": "string | null", "required": false, "example": "mia@hautliebe.de", "description": "Public contact email, if known.", "constraints": [] }, { "name": "creators.followers", "type": "integer", "required": false, "example": 8400, "description": "Follower count.", "constraints": [ "min 0" ] }, { "name": "creators.bio", "type": "string", "required": false, "example": "Skincare + clean beauty. Berlin.", "description": "Profile bio text.", "constraints": [] }, { "name": "creators.profile_url", "type": "string", "required": false, "example": "https://www.instagram.com/hautliebe.mia/", "description": "Derived from platform and handle when omitted.", "constraints": [] }, { "name": "creators.profile_picture_url", "type": "string", "required": false, "example": "https://cdn.example.com/avatars/mia.jpg", "description": "Avatar image URL.", "constraints": [] }, { "name": "creators.location", "type": "string", "required": false, "example": "Berlin", "description": "Free text, e.g. a city or country.", "constraints": [] }, { "name": "creators.language", "type": "string", "required": false, "example": "de", "description": "ISO 639-1 code.", "constraints": [] }, { "name": "creators.niche", "type": "string", "required": false, "example": "skincare", "description": "Content vertical.", "constraints": [] }, { "name": "creators.portfolio_url", "type": "string", "required": false, "example": "https://hautliebe.de", "description": "Personal site, link-in-bio page or media kit.", "constraints": [] }, { "name": "creator_search_id", "type": "string", "required": false, "description": "A completed creator search whose results to copy.", "constraints": [] }, { "name": "creator_ids", "type": "string[]", "required": false, "description": "Restrict the copy to these creator ids from the search.", "constraints": [] } ], "example": { "creators": [ { "platform": "instagram", "handle": "hautliebe.mia", "email": "mia@hautliebe.de", "followers": 8400 } ] } }, "response": { "code": "200", "description": "The append result.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list_append" ], "description": "", "constraints": [] }, { "name": "list", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "list.object", "type": "enum", "required": false, "enum": [ "creator_list" ], "description": "", "constraints": [] }, { "name": "list.id", "type": "string", "required": false, "description": "List id, prefixed list_.", "constraints": [] }, { "name": "list.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "list.description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "list.lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "list.last_job_id", "type": "string | null", "required": false, "description": "The most recent creator search or automation run that appended to the list.", "constraints": [] }, { "name": "list.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "list.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "skipped_duplicates", "type": "integer", "required": false, "description": "Creators that were already members.", "constraints": [] }, { "name": "added", "type": "object[]", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "getListLead", "method": "GET", "path": "/v1/lists/{id}/leads/{lead_id}", "group": "Lists", "summary": "Retrieve a lead", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "lead_id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The lead.", "fields": [] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "removeListLead", "method": "DELETE", "path": "/v1/lists/{id}/leads/{lead_id}", "group": "Lists", "summary": "Remove a lead from a list", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "lead_id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "204", "description": "Removed.", "fields": [], "example": null }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] } ] }, { "name": "Creator Searches", "endpoints": [ { "id": "listCreatorSearches", "method": "GET", "path": "/v1/creator-searches", "group": "Creator Searches", "summary": "List creator searches", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] }, { "name": "status", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "queued", "running", "completed", "failed", "canceled" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "Searches, newest first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "creator_search" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.status", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.prompt", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.result_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.finish_reason", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [] }, { "id": "createCreatorSearch", "method": "POST", "path": "/v1/creator-searches", "group": "Creator Searches", "summary": "Start a creator search", "description": "Starts a sourcing job. Describe what you want with `prompt`, with\nstructured `filters`, or both (a supplied filter always overrides what\nthe prompt implies, and the resolved contract is echoed back in\n`interpreted_request`).\n\nWith `background: true` the call answers 202 immediately; poll the\nLocation URL. While the job runs, `progress` and `creators` fill in\nwith everything found so far, so a consumer can start outreach before\nthe job finishes.\n\nHow long a search runs: the job sources the same way the app's chat\nsearch does, until it reaches `max_results` or exhausts the matching\npool, up to a time allowance that scales with `max_results` (30\nseconds per requested creator, at least 10 minutes and at most 40:\n10 creators run up to 10 minutes, 50 up to 25, 100 up to 40). A run\nthat hits the allowance with creators already found completes with\n`finish_reason: execution_limit` and a `search_timeout` warning; run\nthe same request again to continue, since delivered creators are not\nrepeated. A run that hits it with nothing found fails with\n`creator_search_timeout`. For anything beyond a few results use\n`background: true` with a `lead.added` or `creator_search.completed`\nwebhook, or poll; the synchronous wait window is only seconds long.\n\nSet `list_id` to append every creator to a list as it qualifies and to\nnever return anyone already in that list. `exclude_lists` adds more\nlists to dedupe against (for example a do-not-contact list).\n\nWhy a repeat brief returns fewer creators: by default (`dedupe:\nworkspace`) a creator is delivered to a workspace once, across every\nAPI search, even when each run targets a new list. Re-running the same\nbrief therefore only returns creators the workspace has not seen yet,\nand the pool for that brief shrinks with each run. When that happens\nthe completed job carries a `previously_delivered_excluded` warning\nwith the number of matches skipped. Send `dedupe: list` to dedupe only\nagainst `list_id` and `exclude_lists` (previously delivered creators\nmay be returned again).\n\n`Idempotency-Key` is required. Each call consumes one job-creating\ncall from the workspace quota; credits are consumed per returned\ncreator (1 for an index match, 5 for a live-sourced creator).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "prompt", "type": "string", "required": false, "example": "skincare creators in the US with 5k to 50k followers", "description": "Natural-language brief.", "constraints": [ "min length 3", "max length 5000" ] }, { "name": "filters", "type": "object", "required": false, "description": "Structured constraints. Every field is optional; a supplied field\noverrides what the prompt implies. At least one field is required\nwhen `prompt` is omitted.\n", "constraints": [] }, { "name": "filters.platforms", "type": "enum[]", "required": false, "enum": [ "instagram", "tiktok" ], "example": [ "instagram", "tiktok" ], "description": "Platforms to source from. Omit for both.", "constraints": [ "max 2 items" ] }, { "name": "filters.niches", "type": "string[]", "required": false, "example": [ "skincare", "clean beauty" ], "description": "Content verticals the creator must post about. Free text, lower case. Wording that maps to a known family (finance, trading, beauty, grooming, fitness, sports, productivity, tech, gaming, food, coffee and drinks, fashion, travel, outdoors, parenting, mental health, home, cleaning, pets, education, music, arts and crafts, sustainability, automotive) gets that family's native, hashtag and localized discovery vocabulary; anything else is searched as written.", "constraints": [] }, { "name": "filters.exclude_niches", "type": "string[]", "required": false, "example": [ "fitness" ], "description": "Content verticals to leave out. Same format as niches.", "constraints": [] }, { "name": "filters.countries", "type": "string[]", "required": false, "example": [ "US", "CA" ], "description": "Where the creator is based. ISO 3166-1 alpha-2 codes or English country names.", "constraints": [] }, { "name": "filters.exclude_countries", "type": "string[]", "required": false, "example": [ "IN" ], "description": "Countries to leave out. Same format as countries.", "constraints": [] }, { "name": "filters.languages", "type": "string[]", "required": false, "example": [ "en" ], "description": "ISO 639-1 codes. Makes the language a hard requirement.", "constraints": [] }, { "name": "filters.gender", "type": "enum", "required": false, "enum": [ "man", "woman" ], "example": "woman", "description": "Inferred from the profile, best effort. Omit for any.", "constraints": [] }, { "name": "filters.followers", "type": "object", "required": false, "example": { "min": 5000, "max": 50000 }, "description": "Follower band. Send min, max, or both; each is a non-negative integer and min must not exceed max.", "constraints": [] }, { "name": "filters.followers.min", "type": "integer", "required": false, "example": 5000, "description": "Lowest follower count to accept.", "constraints": [ "min 0" ] }, { "name": "filters.followers.max", "type": "integer", "required": false, "example": 50000, "description": "Highest follower count to accept.", "constraints": [ "min 0" ] }, { "name": "filters.require_email", "type": "boolean", "required": false, "example": true, "description": "Only return creators with a public email.", "constraints": [] }, { "name": "filters.brands", "type": "string[]", "required": false, "example": [ "Cal AI" ], "description": "Only creators with a verified recent collaboration with one of these brands (each result carries proof_posts).", "constraints": [] }, { "name": "max_results", "type": "integer", "required": false, "default": 25, "example": 30, "description": "How many creators to return at most.", "constraints": [ "min 1", "max 200" ] }, { "name": "background", "type": "boolean", "required": false, "default": false, "example": true, "description": "Answer 202 immediately instead of waiting up to the wait window.", "constraints": [] }, { "name": "list_id", "type": "string", "required": false, "example": "list_7f3a9c", "description": "Append results to this list and never return its existing members.", "constraints": [] }, { "name": "exclude_lists", "type": "string[]", "required": false, "example": [ "list_do_not_contact" ], "description": "Additional lists whose members are never returned.", "constraints": [ "max 20 items" ] }, { "name": "dedupe", "type": "enum", "required": false, "default": "workspace", "enum": [ "workspace", "list" ], "example": "list", "description": "workspace: never return a creator this workspace already received from any API search. list: only exclude members of list_id and exclude_lists; previously delivered creators may be returned again.", "constraints": [] } ], "example": { "filters": { "platforms": [ "instagram", "tiktok" ], "niches": [ "skincare" ], "countries": [ "US" ], "followers": { "min": 5000, "max": 50000 }, "require_email": true }, "max_results": 30, "list_id": "list_7f3a9c", "exclude_lists": [ "list_do_not_contact" ], "background": true } }, "response": { "code": "200", "description": "The search finished within the wait window (background: false).", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_search" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed", "canceled" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "The brief; synthesized from filters when none was sent.", "constraints": [] }, { "name": "filters", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "exclude_lists", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "dedupe", "type": "enum", "required": false, "enum": [ "workspace", "list" ], "description": "The dedupe mode the job ran with; also echoed in interpreted_request.", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "progress.found", "type": "integer", "required": false, "description": "Creators qualified so far.", "constraints": [] }, { "name": "progress.target", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.phase", "type": "enum", "required": false, "enum": [ "queued", "planning", "sourcing", "finalizing", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "progress.list_added", "type": "integer", "required": false, "description": "Creators appended to list_id so far.", "constraints": [] }, { "name": "interpreted_request", "type": "object", "required": false, "description": "The resolved sourcing contract (target, platforms, niches, locations, exclusions, follower band, languages, gender, email requirement, brands). Present once the job has planned.", "constraints": [] }, { "name": "finish_reason", "type": "enum", "required": false, "enum": [ "target_reached", "sources_exhausted", "filtered_out", "discovery_limit", "credit_limit", "execution_limit", "partial_failure" ], "description": "Why the job stopped. target_reached guarantees result_count == max_results. Any other value means the list is short: sources_exhausted (no more matching creators), filtered_out (a hard filter such as follower band or email rejected the pool), discovery_limit (the search stopped looking before the target; run it again for more), credit_limit (fewer credits than the request needed), execution_limit (the time allowance, 10 to 40 minutes scaled with max_results, or the processing ceiling was spent before the target; the warnings say which, search_timeout or execution_limit, and a rerun continues from what was delivered), partial_failure (a provider failed mid-run and the search returned what it had). Under the default workspace dedupe, creators already delivered are never repeated on a rerun.", "constraints": [] }, { "name": "result_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "creators", "type": "object[]", "required": false, "description": "Creators found. Grows while the job runs; final on completion.", "constraints": [] }, { "name": "creators.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "creators.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "creators.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "creators.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "creators.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "creators.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "creators.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "creators.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "creators.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "creators.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "creators.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "creators.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "creators.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "creators.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "creators.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "creators.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "creators.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "creators.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "creators.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "creators.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "creators.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "creators.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "creators.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.requested_creators", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.returned_creators", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "warnings", "type": "object[]", "required": false, "description": "Non-fatal notes about the result. Codes: execution_limit (processing ceiling spent before the target), search_timeout (the time allowance ended with creators already found; the job is completed and rerun continues, delivered creators are not repeated), partial_provider_failure, cross_source_dedup (creators found live duplicated index matches and were removed after sourcing stopped, so the list is short), previously_delivered_excluded (the list is short and `count` matching creators were skipped because this workspace already received them from an earlier search; rerun with `dedupe: list` to allow them again).", "constraints": [] }, { "name": "warnings.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "warnings.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "warnings.count", "type": "integer", "required": false, "description": "Only on previously_delivered_excluded.", "constraints": [] }, { "name": "partial_result", "type": "boolean", "required": false, "description": "On a failed job, true when creators holds what was found before the failure.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace credit pool is exhausted for this cycle." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getCreatorSearch", "method": "GET", "path": "/v1/creator-searches/{id}", "group": "Creator Searches", "summary": "Retrieve a creator search", "description": "The job in its current state. `status` moves queued -> running ->\ncompleted | failed | canceled. While running, `progress.found` and\n`creators` grow as creators qualify; `progress.list_added` counts what\nhas already been appended to `list_id`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The search.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_search" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed", "canceled" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "The brief; synthesized from filters when none was sent.", "constraints": [] }, { "name": "filters", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "exclude_lists", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "dedupe", "type": "enum", "required": false, "enum": [ "workspace", "list" ], "description": "The dedupe mode the job ran with; also echoed in interpreted_request.", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "progress.found", "type": "integer", "required": false, "description": "Creators qualified so far.", "constraints": [] }, { "name": "progress.target", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.phase", "type": "enum", "required": false, "enum": [ "queued", "planning", "sourcing", "finalizing", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "progress.list_added", "type": "integer", "required": false, "description": "Creators appended to list_id so far.", "constraints": [] }, { "name": "interpreted_request", "type": "object", "required": false, "description": "The resolved sourcing contract (target, platforms, niches, locations, exclusions, follower band, languages, gender, email requirement, brands). Present once the job has planned.", "constraints": [] }, { "name": "finish_reason", "type": "enum", "required": false, "enum": [ "target_reached", "sources_exhausted", "filtered_out", "discovery_limit", "credit_limit", "execution_limit", "partial_failure" ], "description": "Why the job stopped. target_reached guarantees result_count == max_results. Any other value means the list is short: sources_exhausted (no more matching creators), filtered_out (a hard filter such as follower band or email rejected the pool), discovery_limit (the search stopped looking before the target; run it again for more), credit_limit (fewer credits than the request needed), execution_limit (the time allowance, 10 to 40 minutes scaled with max_results, or the processing ceiling was spent before the target; the warnings say which, search_timeout or execution_limit, and a rerun continues from what was delivered), partial_failure (a provider failed mid-run and the search returned what it had). Under the default workspace dedupe, creators already delivered are never repeated on a rerun.", "constraints": [] }, { "name": "result_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "creators", "type": "object[]", "required": false, "description": "Creators found. Grows while the job runs; final on completion.", "constraints": [] }, { "name": "creators.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "creators.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "creators.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "creators.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "creators.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "creators.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "creators.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "creators.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "creators.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "creators.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "creators.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "creators.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "creators.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "creators.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "creators.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "creators.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "creators.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "creators.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "creators.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "creators.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "creators.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "creators.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "creators.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.requested_creators", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.returned_creators", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "warnings", "type": "object[]", "required": false, "description": "Non-fatal notes about the result. Codes: execution_limit (processing ceiling spent before the target), search_timeout (the time allowance ended with creators already found; the job is completed and rerun continues, delivered creators are not repeated), partial_provider_failure, cross_source_dedup (creators found live duplicated index matches and were removed after sourcing stopped, so the list is short), previously_delivered_excluded (the list is short and `count` matching creators were skipped because this workspace already received them from an earlier search; rerun with `dedupe: list` to allow them again).", "constraints": [] }, { "name": "warnings.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "warnings.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "warnings.count", "type": "integer", "required": false, "description": "Only on previously_delivered_excluded.", "constraints": [] }, { "name": "partial_result", "type": "boolean", "required": false, "description": "On a failed job, true when creators holds what was found before the failure.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "deleteCreatorSearch", "method": "DELETE", "path": "/v1/creator-searches/{id}", "group": "Creator Searches", "summary": "Delete a creator search", "description": "Removes the job and its stored results. List memberships it created are kept.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "cancelCreatorSearch", "method": "POST", "path": "/v1/creator-searches/{id}/cancel", "group": "Creator Searches", "summary": "Cancel a creator search", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The canceled search.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_search" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed", "canceled" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "The brief; synthesized from filters when none was sent.", "constraints": [] }, { "name": "filters", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "exclude_lists", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "dedupe", "type": "enum", "required": false, "enum": [ "workspace", "list" ], "description": "The dedupe mode the job ran with; also echoed in interpreted_request.", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "progress.found", "type": "integer", "required": false, "description": "Creators qualified so far.", "constraints": [] }, { "name": "progress.target", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.phase", "type": "enum", "required": false, "enum": [ "queued", "planning", "sourcing", "finalizing", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "progress.list_added", "type": "integer", "required": false, "description": "Creators appended to list_id so far.", "constraints": [] }, { "name": "interpreted_request", "type": "object", "required": false, "description": "The resolved sourcing contract (target, platforms, niches, locations, exclusions, follower band, languages, gender, email requirement, brands). Present once the job has planned.", "constraints": [] }, { "name": "finish_reason", "type": "enum", "required": false, "enum": [ "target_reached", "sources_exhausted", "filtered_out", "discovery_limit", "credit_limit", "execution_limit", "partial_failure" ], "description": "Why the job stopped. target_reached guarantees result_count == max_results. Any other value means the list is short: sources_exhausted (no more matching creators), filtered_out (a hard filter such as follower band or email rejected the pool), discovery_limit (the search stopped looking before the target; run it again for more), credit_limit (fewer credits than the request needed), execution_limit (the time allowance, 10 to 40 minutes scaled with max_results, or the processing ceiling was spent before the target; the warnings say which, search_timeout or execution_limit, and a rerun continues from what was delivered), partial_failure (a provider failed mid-run and the search returned what it had). Under the default workspace dedupe, creators already delivered are never repeated on a rerun.", "constraints": [] }, { "name": "result_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "creators", "type": "object[]", "required": false, "description": "Creators found. Grows while the job runs; final on completion.", "constraints": [] }, { "name": "creators.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "creators.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "creators.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "creators.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "creators.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "creators.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "creators.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "creators.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "creators.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "creators.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "creators.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "creators.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "creators.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "creators.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "creators.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "creators.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "creators.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "creators.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "creators.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "creators.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "creators.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "creators.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "creators.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.requested_creators", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.returned_creators", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "warnings", "type": "object[]", "required": false, "description": "Non-fatal notes about the result. Codes: execution_limit (processing ceiling spent before the target), search_timeout (the time allowance ended with creators already found; the job is completed and rerun continues, delivered creators are not repeated), partial_provider_failure, cross_source_dedup (creators found live duplicated index matches and were removed after sourcing stopped, so the list is short), previously_delivered_excluded (the list is short and `count` matching creators were skipped because this workspace already received them from an earlier search; rerun with `dedupe: list` to allow them again).", "constraints": [] }, { "name": "warnings.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "warnings.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "warnings.count", "type": "integer", "required": false, "description": "Only on previously_delivered_excluded.", "constraints": [] }, { "name": "partial_result", "type": "boolean", "required": false, "description": "On a failed job, true when creators holds what was found before the failure.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] } ] }, { "name": "Webhooks", "endpoints": [ { "id": "listWebhooks", "method": "GET", "path": "/v1/webhooks", "group": "Webhooks", "summary": "List webhooks", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "Webhooks, newest first. Secrets are never returned here.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "webhook" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Prefixed wh_.", "constraints": [] }, { "name": "data.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.events", "type": "enum[]", "required": false, "enum": [ "lead.added", "creator_search.completed", "creator_search.failed", "automation_run.completed", "webhook.test" ], "description": "", "constraints": [] }, { "name": "data.list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "active", "disabled" ], "description": "", "constraints": [] }, { "name": "data.disabled_reason", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.consecutive_failures", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.last_delivery_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries", "type": "object[]", "required": false, "description": "The last 20 delivery outcomes, newest first.", "constraints": [] }, { "name": "data.recent_deliveries.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries.event_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries.event_type", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries.status", "type": "enum", "required": false, "enum": [ "pending", "succeeded", "failed" ], "description": "", "constraints": [] }, { "name": "data.recent_deliveries.attempt", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries.status_code", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries.error", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.recent_deliveries.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.secret", "type": "string", "required": false, "description": "Only present in the create response.", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [] }, { "id": "createWebhook", "method": "POST", "path": "/v1/webhooks", "group": "Webhooks", "summary": "Create a webhook", "description": "Registers an HTTPS endpoint. The signing `secret` is returned once, in\nthis response only. Scope the endpoint to one list with `list_id`, or\nleave it unset to receive matching events from every list.\n\nDeliveries are JSON POSTs with `X-UGC-Event`, `X-UGC-Delivery-Id`,\n`X-UGC-Webhook-Id`, `X-UGC-Attempt` and `X-UGC-Signature`\n(`t=,v1=.\">`). Answer\n2xx within 10 seconds. Anything else is retried after 1m, 5m, 30m, 2h\nand 12h; an endpoint that fails 5 deliveries in a row is set to\n`disabled` until you re-enable it with PATCH.\n", "deprecated": false, "comingSoon": false, "params": [], "body": { "fields": [ { "name": "url", "type": "string", "required": true, "example": "https://hooks.example.com/ugc-agent", "description": "Public https endpoint.", "constraints": [] }, { "name": "events", "type": "enum[]", "required": true, "enum": [ "lead.added", "creator_search.completed", "creator_search.failed", "automation_run.completed", "webhook.test" ], "example": [ "lead.added", "creator_search.completed" ], "description": "Event types to deliver.", "constraints": [ "min 1 items" ] }, { "name": "list_id", "type": "string | null", "required": false, "example": "list_7f3a9c", "description": "Only receive events for this list.", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "example": "Instantly outreach", "description": "Free-text label for the endpoint.", "constraints": [ "max length 500" ] }, { "name": "secret", "type": "string", "required": false, "example": "whsec_change_me_to_a_long_random_value", "description": "Bring your own signing secret; one is generated otherwise.", "constraints": [ "min length 16", "max length 256" ] } ], "example": { "url": "https://hooks.example.com/ugc-agent", "events": [ "lead.added", "creator_search.completed" ], "list_id": "list_7f3a9c", "description": "Instantly outreach" } }, "response": { "code": "201", "description": "The webhook, including its secret.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "webhook" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Prefixed wh_.", "constraints": [] }, { "name": "url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "events", "type": "enum[]", "required": false, "enum": [ "lead.added", "creator_search.completed", "creator_search.failed", "automation_run.completed", "webhook.test" ], "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "active", "disabled" ], "description": "", "constraints": [] }, { "name": "disabled_reason", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "consecutive_failures", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "last_delivery_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries", "type": "object[]", "required": false, "description": "The last 20 delivery outcomes, newest first.", "constraints": [] }, { "name": "recent_deliveries.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.event_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.event_type", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.status", "type": "enum", "required": false, "enum": [ "pending", "succeeded", "failed" ], "description": "", "constraints": [] }, { "name": "recent_deliveries.attempt", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.status_code", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.error", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "secret", "type": "string", "required": false, "description": "Only present in the create response.", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" } ] }, { "id": "getWebhook", "method": "GET", "path": "/v1/webhooks/{id}", "group": "Webhooks", "summary": "Retrieve a webhook", "description": "Includes the last 20 delivery outcomes for debugging.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The webhook.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "webhook" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Prefixed wh_.", "constraints": [] }, { "name": "url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "events", "type": "enum[]", "required": false, "enum": [ "lead.added", "creator_search.completed", "creator_search.failed", "automation_run.completed", "webhook.test" ], "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "active", "disabled" ], "description": "", "constraints": [] }, { "name": "disabled_reason", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "consecutive_failures", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "last_delivery_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries", "type": "object[]", "required": false, "description": "The last 20 delivery outcomes, newest first.", "constraints": [] }, { "name": "recent_deliveries.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.event_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.event_type", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.status", "type": "enum", "required": false, "enum": [ "pending", "succeeded", "failed" ], "description": "", "constraints": [] }, { "name": "recent_deliveries.attempt", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.status_code", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.error", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "secret", "type": "string", "required": false, "description": "Only present in the create response.", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "updateWebhook", "method": "PATCH", "path": "/v1/webhooks/{id}", "group": "Webhooks", "summary": "Update a webhook", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": { "fields": [ { "name": "url", "type": "string", "required": false, "example": "https://hooks.example.com/ugc-agent", "description": "Public https endpoint.", "constraints": [] }, { "name": "events", "type": "enum[]", "required": false, "enum": [ "lead.added", "creator_search.completed", "creator_search.failed", "automation_run.completed", "webhook.test" ], "example": [ "lead.added" ], "description": "Replaces the subscribed event types.", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "example": "list_7f3a9c", "description": "Only receive events for this list; null for all lists.", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "example": "Instantly outreach", "description": "Free-text label for the endpoint.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "active", "disabled" ], "description": "Set active to re-enable an endpoint that was disabled after repeated failures.", "constraints": [] } ] }, "response": { "code": "200", "description": "The updated webhook.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "webhook" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Prefixed wh_.", "constraints": [] }, { "name": "url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "events", "type": "enum[]", "required": false, "enum": [ "lead.added", "creator_search.completed", "creator_search.failed", "automation_run.completed", "webhook.test" ], "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "active", "disabled" ], "description": "", "constraints": [] }, { "name": "disabled_reason", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "consecutive_failures", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "last_delivery_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries", "type": "object[]", "required": false, "description": "The last 20 delivery outcomes, newest first.", "constraints": [] }, { "name": "recent_deliveries.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.event_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.event_type", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.status", "type": "enum", "required": false, "enum": [ "pending", "succeeded", "failed" ], "description": "", "constraints": [] }, { "name": "recent_deliveries.attempt", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.status_code", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.error", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "recent_deliveries.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "secret", "type": "string", "required": false, "description": "Only present in the create response.", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "deleteWebhook", "method": "DELETE", "path": "/v1/webhooks/{id}", "group": "Webhooks", "summary": "Delete a webhook", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "testWebhook", "method": "POST", "path": "/v1/webhooks/{id}/test", "group": "Webhooks", "summary": "Send a test event", "description": "Sends one signed `webhook.test` event and reports the endpoint's answer. Not retried.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The outcome of the test delivery.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "webhook_test" ], "description": "", "constraints": [] }, { "name": "delivered", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "status_code", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "event_id", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] } ] }, { "name": "Automations", "endpoints": [ { "id": "listAutomations", "method": "GET", "path": "/v1/automations", "group": "Automations", "summary": "List automations", "description": "API-created automations of both types, newest first. Branch on `type`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "Automations, newest first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "automation" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "For trend research, \" trend research\".", "constraints": [] }, { "name": "data.prompt", "type": "string", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.lead_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.list_id", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.topic", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "data.region", "type": "enum", "required": false, "enum": [ "Global" ], "description": "trend_research only. Always Global.", "constraints": [] }, { "name": "data.schedule", "type": "object", "required": false, "example": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "description": "When runs start. weekday is required for weekly and biweekly, day_of_month for monthly, and each is rejected for any other frequency (irrelevant_schedule_field).", "constraints": [] }, { "name": "data.schedule.frequency", "type": "enum", "required": true, "enum": [ "daily", "weekdays", "weekly", "biweekly", "monthly" ], "example": "daily", "description": "How often a run starts.", "constraints": [] }, { "name": "data.schedule.time", "type": "string", "required": true, "example": "08:00", "description": "HH:MM, 24-hour, in timezone.", "constraints": [] }, { "name": "data.schedule.timezone", "type": "string", "required": true, "example": "America/New_York", "description": "IANA timezone. Trend research requires the canonical zone name (Europe/Bucharest, UTC); local, abbreviations and offsets are rejected with invalid_timezone.", "constraints": [ "max length 100" ] }, { "name": "data.schedule.weekday", "type": "integer", "required": false, "example": 1, "description": "ISO weekday (1 = Monday, 7 = Sunday) for weekly and biweekly schedules.", "constraints": [ "min 1", "max 7" ] }, { "name": "data.schedule.day_of_month", "type": "integer | enum", "required": false, "example": 1, "description": "For monthly schedules: 1 to 28, or last.", "constraints": [] }, { "name": "data.recipient_email", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.enabled", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.next_run_at", "type": "string | null", "required": false, "description": "Null while paused.", "constraints": [] }, { "name": "data.last_run_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "Pass as cursor for the next page; null on the last page.", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "createAutomation", "method": "POST", "path": "/v1/automations", "group": "Automations", "summary": "Create an automation", "description": "Two types, chosen with `type`:\n\n- `lead_sourcing`: a recurring sourcing job. Set `list_id` to have every\n run append into a list and dedupe against it, so \"30 more every day\"\n means 30 new creators each morning. Runs are billed like creator\n searches and surface through the same `lead.added` and\n `automation_run.completed` webhook events.\n- `trend_research`: a recurring trend report on a topic, emailed to\n `recipient_email` on the schedule. Every field is required and nothing\n is defaulted: `platform` must be sent, and `schedule.timezone` must be\n a canonical IANA zone (`Europe/Bucharest`, `UTC`); `local`,\n abbreviations such as `EST` and offsets such as `+02:00` answer 400\n `invalid_timezone`. Region is always `Global`, as in the app. Trend\n runs consume no credits, the same as trend automations in the app,\n and do not emit webhook events; read results with GET run.\n\nFields that belong to the other type answer 400 `unknown_parameter`.\nCreating one consumes one job-creating call from the workspace quota\n(an idempotent replay is not counted). A workspace may hold 100\nAPI-created automations, 25 of them enabled, across both types; past\nthat the call answers 409 `automation_limit_reached` or\n`enabled_automation_limit_reached`. Send an `Idempotency-Key` to make\nthe call safe to retry. API-created automations also show in the\nworkspace owner's Automations view in the app; automations created in\nthe app are not listed here.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "type", "type": "enum", "required": true, "enum": [ "lead_sourcing", "trend_research" ], "example": "lead_sourcing", "description": "The kind of automation.", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "example": "skincare creators in the US with 5k to 50k followers", "description": "lead_sourcing only, required. Natural-language brief, same vocabulary as a creator search prompt.", "constraints": [ "min length 1", "max length 5000" ] }, { "name": "lead_count", "type": "integer", "required": false, "example": 30, "description": "lead_sourcing only, required. New creators to produce per run.", "constraints": [ "min 1", "max 1000" ] }, { "name": "list_id", "type": "string | null", "required": false, "example": "list_7f3a9c", "description": "lead_sourcing only. Append each run's creators to this list and dedupe against it.", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "example": "skincare hooks", "description": "trend_research only, required. What to research trends for.", "constraints": [ "min length 1", "max length 200" ] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "example": "tiktok", "description": "trend_research only, required. Where to look for trends. Not defaulted.", "constraints": [] }, { "name": "schedule", "type": "object", "required": true, "example": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "description": "When runs start. weekday is required for weekly and biweekly, day_of_month for monthly, and each is rejected for any other frequency (irrelevant_schedule_field).", "constraints": [] }, { "name": "schedule.frequency", "type": "enum", "required": true, "enum": [ "daily", "weekdays", "weekly", "biweekly", "monthly" ], "example": "daily", "description": "How often a run starts.", "constraints": [] }, { "name": "schedule.time", "type": "string", "required": true, "example": "08:00", "description": "HH:MM, 24-hour, in timezone.", "constraints": [] }, { "name": "schedule.timezone", "type": "string", "required": true, "example": "America/New_York", "description": "IANA timezone. Trend research requires the canonical zone name (Europe/Bucharest, UTC); local, abbreviations and offsets are rejected with invalid_timezone.", "constraints": [ "max length 100" ] }, { "name": "schedule.weekday", "type": "integer", "required": false, "example": 1, "description": "ISO weekday (1 = Monday, 7 = Sunday) for weekly and biweekly schedules.", "constraints": [ "min 1", "max 7" ] }, { "name": "schedule.day_of_month", "type": "integer | enum", "required": false, "example": 1, "description": "For monthly schedules: 1 to 28, or last.", "constraints": [] }, { "name": "recipient_email", "type": "string", "required": true, "example": "ops@example.com", "description": "Receives the scheduled email (lead summary or trend report).", "constraints": [ "max length 320" ] }, { "name": "run_immediately", "type": "boolean", "required": false, "default": false, "example": true, "description": "Also queue one manual run right away. Manual runs do not send email; read the result with GET run.", "constraints": [] } ], "example": { "type": "lead_sourcing", "prompt": "skincare creators in the US with 5k to 50k followers", "lead_count": 30, "schedule": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "recipient_email": "ops@example.com", "list_id": "list_7f3a9c", "run_immediately": true } }, "response": { "code": "201", "description": "The automation.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "For trend research, \" trend research\".", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "lead_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "region", "type": "enum", "required": false, "enum": [ "Global" ], "description": "trend_research only. Always Global.", "constraints": [] }, { "name": "schedule", "type": "object", "required": false, "example": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "description": "When runs start. weekday is required for weekly and biweekly, day_of_month for monthly, and each is rejected for any other frequency (irrelevant_schedule_field).", "constraints": [] }, { "name": "schedule.frequency", "type": "enum", "required": true, "enum": [ "daily", "weekdays", "weekly", "biweekly", "monthly" ], "example": "daily", "description": "How often a run starts.", "constraints": [] }, { "name": "schedule.time", "type": "string", "required": true, "example": "08:00", "description": "HH:MM, 24-hour, in timezone.", "constraints": [] }, { "name": "schedule.timezone", "type": "string", "required": true, "example": "America/New_York", "description": "IANA timezone. Trend research requires the canonical zone name (Europe/Bucharest, UTC); local, abbreviations and offsets are rejected with invalid_timezone.", "constraints": [ "max length 100" ] }, { "name": "schedule.weekday", "type": "integer", "required": false, "example": 1, "description": "ISO weekday (1 = Monday, 7 = Sunday) for weekly and biweekly schedules.", "constraints": [ "min 1", "max 7" ] }, { "name": "schedule.day_of_month", "type": "integer | enum", "required": false, "example": 1, "description": "For monthly schedules: 1 to 28, or last.", "constraints": [] }, { "name": "recipient_email", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "enabled", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "next_run_at", "type": "string | null", "required": false, "description": "Null while paused.", "constraints": [] }, { "name": "last_run_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "automation", "id": "api_auto_3f9c2b", "type": "trend_research", "name": "skincare hooks trend research", "topic": "skincare hooks", "platform": "tiktok", "region": "Global", "schedule": { "frequency": "weekly", "time": "08:30", "timezone": "Europe/Bucharest", "weekday": 1 }, "recipient_email": "ops@example.com", "enabled": true, "created_at": "2026-10-07T12:00:00.000Z", "updated_at": "2026-10-07T12:00:00.000Z", "next_run_at": "2026-10-12T05:30:00.000Z", "last_run_at": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." } ] }, { "id": "getAutomation", "method": "GET", "path": "/v1/automations/{id}", "group": "Automations", "summary": "Retrieve an automation", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id, as returned on create.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The automation, in the shape for its type.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "For trend research, \" trend research\".", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "lead_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "region", "type": "enum", "required": false, "enum": [ "Global" ], "description": "trend_research only. Always Global.", "constraints": [] }, { "name": "schedule", "type": "object", "required": false, "example": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "description": "When runs start. weekday is required for weekly and biweekly, day_of_month for monthly, and each is rejected for any other frequency (irrelevant_schedule_field).", "constraints": [] }, { "name": "schedule.frequency", "type": "enum", "required": true, "enum": [ "daily", "weekdays", "weekly", "biweekly", "monthly" ], "example": "daily", "description": "How often a run starts.", "constraints": [] }, { "name": "schedule.time", "type": "string", "required": true, "example": "08:00", "description": "HH:MM, 24-hour, in timezone.", "constraints": [] }, { "name": "schedule.timezone", "type": "string", "required": true, "example": "America/New_York", "description": "IANA timezone. Trend research requires the canonical zone name (Europe/Bucharest, UTC); local, abbreviations and offsets are rejected with invalid_timezone.", "constraints": [ "max length 100" ] }, { "name": "schedule.weekday", "type": "integer", "required": false, "example": 1, "description": "ISO weekday (1 = Monday, 7 = Sunday) for weekly and biweekly schedules.", "constraints": [ "min 1", "max 7" ] }, { "name": "schedule.day_of_month", "type": "integer | enum", "required": false, "example": 1, "description": "For monthly schedules: 1 to 28, or last.", "constraints": [] }, { "name": "recipient_email", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "enabled", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "next_run_at", "type": "string | null", "required": false, "description": "Null while paused.", "constraints": [] }, { "name": "last_run_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "updateAutomation", "method": "PATCH", "path": "/v1/automations/{id}", "group": "Automations", "summary": "Update an automation", "description": "Send only the fields to change. Which fields are accepted depends on the\nstored type; any other field answers 400 `invalid_parameter_for_type`\nwith `param` set:\n- lead_sourcing: `prompt`, `lead_count`, `schedule`, `recipient_email`, `enabled`, `list_id`\n- trend_research: `topic`, `platform`, `schedule`, `recipient_email`, `enabled`\n\n`schedule` replaces the whole schedule, so restate the timezone. For\ntrend research it must be a canonical IANA zone. Changing `topic`\nrenames the automation to \" trend research\", as in the app.\n`enabled: false` pauses the schedule (`next_run_at` becomes null)\nwithout deleting the automation. An automation with a run in progress\nanswers 409 `automation_run_active`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id, as returned on create.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "prompt", "type": "string", "required": false, "example": "skincare creators in the US with 5k to 50k followers", "description": "lead_sourcing only. Replaces the brief.", "constraints": [ "min length 1", "max length 5000" ] }, { "name": "lead_count", "type": "integer", "required": false, "example": 30, "description": "lead_sourcing only. New creators to produce per run.", "constraints": [ "min 1", "max 1000" ] }, { "name": "list_id", "type": "string | null", "required": false, "example": "list_7f3a9c", "description": "lead_sourcing only. Append each run's creators to this list; null to stop appending.", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "example": "skincare hooks", "description": "trend_research only. Replaces the topic and renames the automation.", "constraints": [ "min length 1", "max length 200" ] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "example": "both", "description": "trend_research only. Where to look for trends.", "constraints": [] }, { "name": "schedule", "type": "object", "required": false, "example": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "description": "When runs start. weekday is required for weekly and biweekly, day_of_month for monthly, and each is rejected for any other frequency (irrelevant_schedule_field).", "constraints": [] }, { "name": "schedule.frequency", "type": "enum", "required": true, "enum": [ "daily", "weekdays", "weekly", "biweekly", "monthly" ], "example": "daily", "description": "How often a run starts.", "constraints": [] }, { "name": "schedule.time", "type": "string", "required": true, "example": "08:00", "description": "HH:MM, 24-hour, in timezone.", "constraints": [] }, { "name": "schedule.timezone", "type": "string", "required": true, "example": "America/New_York", "description": "IANA timezone. Trend research requires the canonical zone name (Europe/Bucharest, UTC); local, abbreviations and offsets are rejected with invalid_timezone.", "constraints": [ "max length 100" ] }, { "name": "schedule.weekday", "type": "integer", "required": false, "example": 1, "description": "ISO weekday (1 = Monday, 7 = Sunday) for weekly and biweekly schedules.", "constraints": [ "min 1", "max 7" ] }, { "name": "schedule.day_of_month", "type": "integer | enum", "required": false, "example": 1, "description": "For monthly schedules: 1 to 28, or last.", "constraints": [] }, { "name": "recipient_email", "type": "string", "required": false, "example": "ops@example.com", "description": "Receives the scheduled email.", "constraints": [ "max length 320" ] }, { "name": "enabled", "type": "boolean", "required": false, "example": true, "description": "false pauses the schedule without deleting the automation.", "constraints": [] } ], "example": { "schedule": { "frequency": "weekdays", "time": "09:00", "timezone": "Europe/Bucharest" }, "enabled": true } }, "response": { "code": "200", "description": "The updated automation.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "For trend research, \" trend research\".", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "lead_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "region", "type": "enum", "required": false, "enum": [ "Global" ], "description": "trend_research only. Always Global.", "constraints": [] }, { "name": "schedule", "type": "object", "required": false, "example": { "frequency": "daily", "time": "08:00", "timezone": "America/New_York" }, "description": "When runs start. weekday is required for weekly and biweekly, day_of_month for monthly, and each is rejected for any other frequency (irrelevant_schedule_field).", "constraints": [] }, { "name": "schedule.frequency", "type": "enum", "required": true, "enum": [ "daily", "weekdays", "weekly", "biweekly", "monthly" ], "example": "daily", "description": "How often a run starts.", "constraints": [] }, { "name": "schedule.time", "type": "string", "required": true, "example": "08:00", "description": "HH:MM, 24-hour, in timezone.", "constraints": [] }, { "name": "schedule.timezone", "type": "string", "required": true, "example": "America/New_York", "description": "IANA timezone. Trend research requires the canonical zone name (Europe/Bucharest, UTC); local, abbreviations and offsets are rejected with invalid_timezone.", "constraints": [ "max length 100" ] }, { "name": "schedule.weekday", "type": "integer", "required": false, "example": 1, "description": "ISO weekday (1 = Monday, 7 = Sunday) for weekly and biweekly schedules.", "constraints": [ "min 1", "max 7" ] }, { "name": "schedule.day_of_month", "type": "integer | enum", "required": false, "example": 1, "description": "For monthly schedules: 1 to 28, or last.", "constraints": [] }, { "name": "recipient_email", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "enabled", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "next_run_at", "type": "string | null", "required": false, "description": "Null while paused.", "constraints": [] }, { "name": "last_run_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "deleteAutomation", "method": "DELETE", "path": "/v1/automations/{id}", "group": "Automations", "summary": "Delete an automation", "description": "Deletes the automation and stops future runs. Supports `Idempotency-Key`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id, as returned on create.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "listAutomationRuns", "method": "GET", "path": "/v1/automations/{id}/runs", "group": "Automations", "summary": "List runs", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id.", "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "Runs, newest first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "automation_run" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.automation_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.automation_type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "data.trigger", "type": "enum", "required": false, "enum": [ "manual", "scheduled", "setup_test" ], "description": "manual runs (run now, run_immediately) never send email.", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "queued", "running", "succeeded", "partial", "failed", "quota_blocked", "canceled" ], "description": "", "constraints": [] }, { "name": "data.phase", "type": "enum", "required": false, "enum": [ "researching", "generating", "delivering", null ], "description": "trend_research only. Null while queued.", "constraints": [] }, { "name": "data.progress", "type": "object", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.progress.discovered", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.progress.processed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.progress.kept", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.produced_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.started_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.result", "type": "object | null", "required": false, "description": "Null until the run succeeds (or partially succeeds).", "constraints": [] }, { "name": "data.result.summary", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.result.locator", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.result.creators", "type": "object[]", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "data.result.usage", "type": "object", "required": false, "description": "lead_sourcing only: pricing_version, credits_consumed, breakdown.", "constraints": [] }, { "name": "data.result.topic", "type": "string", "required": false, "description": "trend_research only. From here down, the result has the same shape as a completed GET /v1/trend-researches/{id} (plus summary).", "constraints": [] }, { "name": "data.result.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "data.result.region", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.result.researched_at", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.result.evidence_mode", "type": "enum", "required": false, "enum": [ "social", "web", "none" ], "description": "trend_research only. Whether trends rest on social posts, web sources, or neither.", "constraints": [] }, { "name": "data.result.social_retrieval_status", "type": "enum", "required": false, "enum": [ "complete", "partial", "empty", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "data.result.synthesis_status", "type": "enum", "required": false, "enum": [ "succeeded", "no_evidence", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "data.result.trends", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.result.direct_proof_posts", "type": "object[]", "required": false, "description": "trend_research only. caption, views, likes, comments, shares and source may be null on runs stored before they were recorded.", "constraints": [] }, { "name": "data.result.cited_web_sources", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.result.web_claims", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.result.notes", "type": "string[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "data.delivery", "type": "object | null", "required": false, "description": "Email delivery state; null when no email was requested (manual runs).", "constraints": [] }, { "name": "data.delivery.status", "type": "enum", "required": false, "enum": [ "pending", "sending", "retry_wait", "sent", "failed", "skipped" ], "description": "", "constraints": [] }, { "name": "data.delivery.delivered_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.error", "type": "object | null", "required": false, "description": "Codes: credits_exhausted (lead_sourcing), trend_generation_failed (trend_research), automation_run_timeout, automation_deleted, automation_run_failed.", "constraints": [] }, { "name": "data.error.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.error.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "Pass as cursor for the next page; null on the last page.", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "startAutomationRun", "method": "POST", "path": "/v1/automations/{id}/runs", "group": "Automations", "summary": "Run now", "description": "Starts a run immediately instead of waiting for the schedule. No body.\nA manual run never sends the summary email; read the result with GET\nrun. Consumes one job-creating call from the workspace quota. A lead\nsourcing run consumes credits like a creator search; a trend research\nrun consumes none. 409 `automation_run_active` when a run is already in\nprogress.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "202", "description": "The run was queued.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation_run" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "automation_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "automation_type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "trigger", "type": "enum", "required": false, "enum": [ "manual", "scheduled", "setup_test" ], "description": "manual runs (run now, run_immediately) never send email.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "succeeded", "partial", "failed", "quota_blocked", "canceled" ], "description": "", "constraints": [] }, { "name": "phase", "type": "enum", "required": false, "enum": [ "researching", "generating", "delivering", null ], "description": "trend_research only. Null while queued.", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "progress.discovered", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.processed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.kept", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "produced_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "started_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result", "type": "object | null", "required": false, "description": "Null until the run succeeds (or partially succeeds).", "constraints": [] }, { "name": "result.summary", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.locator", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "result.creators", "type": "object[]", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "result.creators.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "result.creators.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "result.creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "result.creators.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "result.creators.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "result.creators.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "result.creators.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "result.creators.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "result.creators.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "result.creators.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "result.creators.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "result.creators.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "result.creators.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "result.creators.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "result.creators.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "result.creators.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "result.creators.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "result.creators.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "result.creators.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "result.creators.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "result.creators.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "result.creators.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "result.creators.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "result.creators.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "result.usage", "type": "object", "required": false, "description": "lead_sourcing only: pricing_version, credits_consumed, breakdown.", "constraints": [] }, { "name": "result.topic", "type": "string", "required": false, "description": "trend_research only. From here down, the result has the same shape as a completed GET /v1/trend-researches/{id} (plus summary).", "constraints": [] }, { "name": "result.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.region", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.researched_at", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.evidence_mode", "type": "enum", "required": false, "enum": [ "social", "web", "none" ], "description": "trend_research only. Whether trends rest on social posts, web sources, or neither.", "constraints": [] }, { "name": "result.social_retrieval_status", "type": "enum", "required": false, "enum": [ "complete", "partial", "empty", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.synthesis_status", "type": "enum", "required": false, "enum": [ "succeeded", "no_evidence", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.trends", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.trends.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "web" ], "description": "web: a web-grounded signal cited only to W sources.", "constraints": [] }, { "name": "result.trends.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.trends.observation", "type": "string", "required": false, "description": "What the evidence shows.", "constraints": [] }, { "name": "result.trends.how_to_use", "type": "string", "required": false, "description": "How to apply it in a UGC video.", "constraints": [] }, { "name": "result.trends.evidence", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts", "type": "object[]", "required": false, "description": "trend_research only. caption, views, likes, comments, shares and source may be null on runs stored before they were recorded.", "constraints": [] }, { "name": "result.direct_proof_posts.id", "type": "string", "required": false, "description": "S.", "constraints": [] }, { "name": "result.direct_proof_posts.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.author", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.caption", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.hook", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.sound", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.comments", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.shares", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.source", "type": "enum", "required": false, "enum": [ "platform_api", "web_index", null ], "description": "web_index: found through a web index because the platform returned nothing.", "constraints": [] }, { "name": "result.cited_web_sources", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.cited_web_sources.id", "type": "string", "required": false, "description": "W.", "constraints": [] }, { "name": "result.cited_web_sources.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.cited_web_sources.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.web_claims", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.web_claims.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.web_claims.source_ids", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "result.notes", "type": "string[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "delivery", "type": "object | null", "required": false, "description": "Email delivery state; null when no email was requested (manual runs).", "constraints": [] }, { "name": "delivery.status", "type": "enum", "required": false, "enum": [ "pending", "sending", "retry_wait", "sent", "failed", "skipped" ], "description": "", "constraints": [] }, { "name": "delivery.delivered_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "Codes: credits_exhausted (lead_sourcing), trend_generation_failed (trend_research), automation_run_timeout, automation_deleted, automation_run_failed.", "constraints": [] }, { "name": "error.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "error.message", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace credit pool is exhausted for this cycle." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getAutomationRun", "method": "GET", "path": "/v1/automations/{id}/runs/{run_id}", "group": "Automations", "summary": "Retrieve a run", "description": "The run in its current state. Branch on `automation_type`: lead\nsourcing runs carry `progress`, `produced_count` and the creators in\n`result`; trend research runs carry `phase` and the trends with their\nevidence in `result`. `result` is null until the run succeeds.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id.", "constraints": [] }, { "name": "run_id", "in": "path", "required": true, "type": "string", "description": "Run id.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The run.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation_run" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "automation_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "automation_type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "trigger", "type": "enum", "required": false, "enum": [ "manual", "scheduled", "setup_test" ], "description": "manual runs (run now, run_immediately) never send email.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "succeeded", "partial", "failed", "quota_blocked", "canceled" ], "description": "", "constraints": [] }, { "name": "phase", "type": "enum", "required": false, "enum": [ "researching", "generating", "delivering", null ], "description": "trend_research only. Null while queued.", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "progress.discovered", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.processed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.kept", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "produced_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "started_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result", "type": "object | null", "required": false, "description": "Null until the run succeeds (or partially succeeds).", "constraints": [] }, { "name": "result.summary", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.locator", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "result.creators", "type": "object[]", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "result.creators.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "result.creators.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "result.creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "result.creators.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "result.creators.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "result.creators.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "result.creators.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "result.creators.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "result.creators.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "result.creators.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "result.creators.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "result.creators.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "result.creators.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "result.creators.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "result.creators.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "result.creators.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "result.creators.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "result.creators.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "result.creators.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "result.creators.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "result.creators.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "result.creators.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "result.creators.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "result.creators.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "result.usage", "type": "object", "required": false, "description": "lead_sourcing only: pricing_version, credits_consumed, breakdown.", "constraints": [] }, { "name": "result.topic", "type": "string", "required": false, "description": "trend_research only. From here down, the result has the same shape as a completed GET /v1/trend-researches/{id} (plus summary).", "constraints": [] }, { "name": "result.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.region", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.researched_at", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.evidence_mode", "type": "enum", "required": false, "enum": [ "social", "web", "none" ], "description": "trend_research only. Whether trends rest on social posts, web sources, or neither.", "constraints": [] }, { "name": "result.social_retrieval_status", "type": "enum", "required": false, "enum": [ "complete", "partial", "empty", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.synthesis_status", "type": "enum", "required": false, "enum": [ "succeeded", "no_evidence", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.trends", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.trends.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "web" ], "description": "web: a web-grounded signal cited only to W sources.", "constraints": [] }, { "name": "result.trends.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.trends.observation", "type": "string", "required": false, "description": "What the evidence shows.", "constraints": [] }, { "name": "result.trends.how_to_use", "type": "string", "required": false, "description": "How to apply it in a UGC video.", "constraints": [] }, { "name": "result.trends.evidence", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts", "type": "object[]", "required": false, "description": "trend_research only. caption, views, likes, comments, shares and source may be null on runs stored before they were recorded.", "constraints": [] }, { "name": "result.direct_proof_posts.id", "type": "string", "required": false, "description": "S.", "constraints": [] }, { "name": "result.direct_proof_posts.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.author", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.caption", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.hook", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.sound", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.comments", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.shares", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.source", "type": "enum", "required": false, "enum": [ "platform_api", "web_index", null ], "description": "web_index: found through a web index because the platform returned nothing.", "constraints": [] }, { "name": "result.cited_web_sources", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.cited_web_sources.id", "type": "string", "required": false, "description": "W.", "constraints": [] }, { "name": "result.cited_web_sources.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.cited_web_sources.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.web_claims", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.web_claims.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.web_claims.source_ids", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "result.notes", "type": "string[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "delivery", "type": "object | null", "required": false, "description": "Email delivery state; null when no email was requested (manual runs).", "constraints": [] }, { "name": "delivery.status", "type": "enum", "required": false, "enum": [ "pending", "sending", "retry_wait", "sent", "failed", "skipped" ], "description": "", "constraints": [] }, { "name": "delivery.delivered_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "Codes: credits_exhausted (lead_sourcing), trend_generation_failed (trend_research), automation_run_timeout, automation_deleted, automation_run_failed.", "constraints": [] }, { "name": "error.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "error.message", "type": "string", "required": false, "description": "", "constraints": [] } ], "example": { "object": "automation_run", "id": "api_run_8d21e0", "automation_id": "api_auto_3f9c2b", "automation_type": "trend_research", "trigger": "manual", "status": "succeeded", "phase": "delivering", "created_at": "2026-10-07T10:00:00.000Z", "started_at": "2026-10-07T10:00:02.000Z", "completed_at": "2026-10-07T10:01:40.000Z", "result": { "summary": "1 trend found.", "topic": "skincare hooks", "platform": "tiktok", "region": "Global", "researched_at": "2026-10-07T10:01:30.000Z", "evidence_mode": "social", "social_retrieval_status": "complete", "synthesis_status": "succeeded", "trends": [ { "platform": "tiktok", "title": "Before and after splits", "observation": "Split screens lead the top posts.", "how_to_use": "Open on the after shot.", "evidence": [ { "id": "S1", "kind": "social", "platform": "tiktok", "title": "Wait for it", "url": "https://www.tiktok.com/@example/video/1" }, { "id": "W1", "kind": "web", "platform": null, "title": "Report", "url": "https://example.com/report" } ] } ], "direct_proof_posts": [ { "id": "S1", "platform": "tiktok", "url": "https://www.tiktok.com/@example/video/1", "author": "example", "caption": "Wait for the after shot", "hook": "Wait for it", "sound": null, "hashtags": [ "skincare" ], "views": 182000, "likes": 9100, "comments": 240, "shares": 610, "posted_at": "2026-10-05T18:00:00.000Z", "source": "platform_api" } ], "cited_web_sources": [ { "id": "W1", "title": "Report", "url": "https://example.com/report" } ], "web_claims": [], "notes": [] }, "delivery": null, "error": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "testAutomationDelivery", "method": "POST", "path": "/v1/automations/{id}/test-delivery", "group": "Automations", "summary": "Send a test email", "description": "Sends the app's fixed-sample lead email to the automation's\n`recipient_email` so you can check it arrives. No run is created and\nnothing is charged. Lead sourcing automations only: a trend research\nautomation answers 409 `test_delivery_unsupported`. No body.\n\nWith an `Idempotency-Key` a repeat returns the stored result and the\nemail is sent once; without one, every call sends an email.\n\nOther errors: 409 `test_delivery_disabled` (live delivery is off on\nthis deployment, same gate as the app), 503 `email_delivery_unavailable`\nor `test_delivery_unavailable`, 502 `email_provider_failed`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The test email was sent.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation_test_delivery" ], "description": "", "constraints": [] }, { "name": "automation_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "sent" ], "description": "", "constraints": [] }, { "name": "recipient_email", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "provider_message_id", "type": "string", "required": false, "description": "The email provider's message id.", "constraints": [] }, { "name": "sent_at", "type": "string", "required": false, "description": "", "constraints": [] } ], "example": { "object": "automation_test_delivery", "automation_id": "api_auto_3f9c2b", "status": "sent", "recipient_email": "ops@example.com", "provider_message_id": "re_123", "sent_at": "2026-10-07T12:00:00.000Z" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "502", "description": "The email provider refused the message (email_provider_failed)." }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "retryAutomationRunDelivery", "method": "POST", "path": "/v1/automations/{id}/runs/{run_id}/retry-delivery", "group": "Automations", "summary": "Retry a failed email", "description": "Re-sends the summary email for a run whose delivery failed and returns\nthe updated run. Nothing is charged. No body. The same eligibility rules\nas the app apply: the run must be `succeeded` or `partial`, scheduled\n(manual runs never email), with `delivery.status` `failed`, and either a\nlead sourcing run that produced at least one creator or any trend\nresearch run. Otherwise 409 `delivery_retry_not_eligible`; a delivery\nalready under way answers 409 `delivery_in_progress`.\n\nWith an `Idempotency-Key` a replay returns the current run without\nsending again. Other errors: 404 `automation_run_not_found`, 409\n`delivery_disabled`, 503 `email_delivery_unavailable`, 502\n`email_provider_failed`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Automation id.", "constraints": [] }, { "name": "run_id", "in": "path", "required": true, "type": "string", "description": "Run id.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The run with its updated delivery state.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "automation_run" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "automation_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "automation_type", "type": "enum", "required": false, "enum": [ "lead_sourcing", "trend_research" ], "description": "", "constraints": [] }, { "name": "trigger", "type": "enum", "required": false, "enum": [ "manual", "scheduled", "setup_test" ], "description": "manual runs (run now, run_immediately) never send email.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "succeeded", "partial", "failed", "quota_blocked", "canceled" ], "description": "", "constraints": [] }, { "name": "phase", "type": "enum", "required": false, "enum": [ "researching", "generating", "delivering", null ], "description": "trend_research only. Null while queued.", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "progress.discovered", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.processed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.kept", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "produced_count", "type": "integer", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "started_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result", "type": "object | null", "required": false, "description": "Null until the run succeeds (or partially succeeds).", "constraints": [] }, { "name": "result.summary", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.locator", "type": "string | null", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "result.creators", "type": "object[]", "required": false, "description": "lead_sourcing only.", "constraints": [] }, { "name": "result.creators.id", "type": "string", "required": false, "description": "Stable id for this creator within the turn.", "constraints": [] }, { "name": "result.creators.handle", "type": "string", "required": false, "description": "The creator's handle", "constraints": [] }, { "name": "result.creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "Where the account lives.", "constraints": [] }, { "name": "result.creators.profile_url", "type": "string", "required": false, "description": "Canonical profile link, derived from the platform and handle.", "constraints": [] }, { "name": "result.creators.profile_picture_url", "type": "string", "required": false, "description": "Avatar URL", "constraints": [] }, { "name": "result.creators.name", "type": "string", "required": false, "description": "Display name as it appears on the profile.", "constraints": [] }, { "name": "result.creators.first_name", "type": "string", "required": false, "description": "Best-effort first name", "constraints": [] }, { "name": "result.creators.followers", "type": "integer", "required": false, "description": "Follower count at the time of the run.", "constraints": [] }, { "name": "result.creators.bio", "type": "string", "required": false, "description": "Profile bio text.", "constraints": [] }, { "name": "result.creators.email", "type": "string", "required": false, "description": "Contact email", "constraints": [] }, { "name": "result.creators.email_type", "type": "string", "required": false, "description": "Whether the address looks personal, business, or agency-operated.", "constraints": [] }, { "name": "result.creators.email_source", "type": "enum", "required": false, "enum": [ "platform", "bio", "portfolio", "serp", "unknown" ], "description": "Where the address was found.", "constraints": [] }, { "name": "result.creators.email_domain_status", "type": "enum", "required": false, "enum": [ "routable", "unchecked", "unknown" ], "description": "Whether the address's domain resolves.", "constraints": [] }, { "name": "result.creators.email_deliverability", "type": "string", "required": false, "description": "Always `unverified` - no mailbox check is performed.", "constraints": [] }, { "name": "result.creators.niche", "type": "string", "required": false, "description": "Inferred content niche.", "constraints": [] }, { "name": "result.creators.location", "type": "string", "required": false, "description": "Location", "constraints": [] }, { "name": "result.creators.language", "type": "string", "required": false, "description": "Profile language code.", "constraints": [] }, { "name": "result.creators.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "Inferred", "constraints": [] }, { "name": "result.creators.fit_score", "type": "number", "required": false, "description": "How well the creator matches the request.", "constraints": [] }, { "name": "result.creators.fit_reasons", "type": "string[]", "required": false, "description": "Evidence behind the score - niche, UGC signals, and location.", "constraints": [] }, { "name": "result.creators.portfolio_url", "type": "string", "required": false, "description": "The creator's bio or portfolio link", "constraints": [] }, { "name": "result.creators.proof_posts", "type": "string[]", "required": false, "description": "Post URLs backing a brand collaboration claim. Empty unless the turn researched brands.", "constraints": [] }, { "name": "result.creators.niche_evidence_url", "type": "string | null", "required": false, "description": "The creator's own post whose caption backed the niche verdict, when qualification read one (post-level, hashtag, or keyword discovery). Null when the verdict rests on the profile alone.", "constraints": [] }, { "name": "result.creators.origin", "type": "enum", "required": false, "enum": [ "vector_database", "live_sourced" ], "description": "Whether the creator came from the shared index or fresh sourcing.", "constraints": [] }, { "name": "result.usage", "type": "object", "required": false, "description": "lead_sourcing only: pricing_version, credits_consumed, breakdown.", "constraints": [] }, { "name": "result.topic", "type": "string", "required": false, "description": "trend_research only. From here down, the result has the same shape as a completed GET /v1/trend-researches/{id} (plus summary).", "constraints": [] }, { "name": "result.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", "both" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.region", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.researched_at", "type": "string", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.evidence_mode", "type": "enum", "required": false, "enum": [ "social", "web", "none" ], "description": "trend_research only. Whether trends rest on social posts, web sources, or neither.", "constraints": [] }, { "name": "result.social_retrieval_status", "type": "enum", "required": false, "enum": [ "complete", "partial", "empty", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.synthesis_status", "type": "enum", "required": false, "enum": [ "succeeded", "no_evidence", "unavailable" ], "description": "trend_research only.", "constraints": [] }, { "name": "result.trends", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.trends.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "web" ], "description": "web: a web-grounded signal cited only to W sources.", "constraints": [] }, { "name": "result.trends.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.trends.observation", "type": "string", "required": false, "description": "What the evidence shows.", "constraints": [] }, { "name": "result.trends.how_to_use", "type": "string", "required": false, "description": "How to apply it in a UGC video.", "constraints": [] }, { "name": "result.trends.evidence", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts", "type": "object[]", "required": false, "description": "trend_research only. caption, views, likes, comments, shares and source may be null on runs stored before they were recorded.", "constraints": [] }, { "name": "result.direct_proof_posts.id", "type": "string", "required": false, "description": "S.", "constraints": [] }, { "name": "result.direct_proof_posts.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.author", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.caption", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.hook", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.sound", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.comments", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.shares", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "result.direct_proof_posts.source", "type": "enum", "required": false, "enum": [ "platform_api", "web_index", null ], "description": "web_index: found through a web index because the platform returned nothing.", "constraints": [] }, { "name": "result.cited_web_sources", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.cited_web_sources.id", "type": "string", "required": false, "description": "W.", "constraints": [] }, { "name": "result.cited_web_sources.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.cited_web_sources.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.web_claims", "type": "object[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "result.web_claims.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "result.web_claims.source_ids", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "result.notes", "type": "string[]", "required": false, "description": "trend_research only.", "constraints": [] }, { "name": "delivery", "type": "object | null", "required": false, "description": "Email delivery state; null when no email was requested (manual runs).", "constraints": [] }, { "name": "delivery.status", "type": "enum", "required": false, "enum": [ "pending", "sending", "retry_wait", "sent", "failed", "skipped" ], "description": "", "constraints": [] }, { "name": "delivery.delivered_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "Codes: credits_exhausted (lead_sourcing), trend_generation_failed (trend_research), automation_run_timeout, automation_deleted, automation_run_failed.", "constraints": [] }, { "name": "error.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "error.message", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "502", "description": "The email provider refused the message (email_provider_failed)." }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] } ] }, { "name": "Chats", "endpoints": [ { "id": "listChats", "method": "GET", "path": "/v1/chats", "group": "Chats", "summary": "List chats", "description": "The chats in the web app sidebar (including chats started from the\nhosted MCP), newest first. Use the id with PATCH /v1/chats/{id} to\nrename one.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 20, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "Chats, newest first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Chat id.", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "chat" ], "description": "", "constraints": [] }, { "name": "data.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 80" ] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "Last time the transcript changed. Renaming does not move it.", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "renameChat", "method": "PATCH", "path": "/v1/chats/{id}", "group": "Chats", "summary": "Rename a chat", "description": "Sets the chat's title everywhere it shows: the web app sidebar, the\nMCP and this API. Whitespace is collapsed and titles are capped at 80\ncharacters. Later turns in the chat keep the new name.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Chat id from GET /v1/chats. URL-encode it (MCP chat ids contain colons).", "constraints": [] } ], "body": { "fields": [ { "name": "title", "type": "string", "required": true, "description": "The new name. Must not be blank.", "constraints": [ "min length 1", "max length 80" ] } ], "example": { "title": "Q4 gifting shortlist" } }, "response": { "code": "200", "description": "The renamed chat.", "fields": [ { "name": "id", "type": "string", "required": false, "description": "Chat id.", "constraints": [] }, { "name": "object", "type": "enum", "required": false, "enum": [ "chat" ], "description": "", "constraints": [] }, { "name": "title", "type": "string", "required": false, "description": "", "constraints": [ "max length 80" ] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "Last time the transcript changed. Renaming does not move it.", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "deleteChat", "method": "DELETE", "path": "/v1/chats/{id}", "group": "Chats", "summary": "Delete a chat", "description": "Permanently deletes a chat, the same way deleting it from the web app\nsidebar does. Any search still running in the chat is stopped first,\nthe chat's share links (chat and result table) are revoked, its\nserver-side results are removed, and then the transcript is deleted.\nThis cannot be undone. Creators you already saved to the Creator CRM\nor appended to a list are not affected.\n\nTakes no query parameters and no body. Answers 404 `chat_not_found`\nwhen no chat with that id belongs to you.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Chat id from GET /v1/chats. URL-encode it (MCP chat ids contain colons).", "constraints": [] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "listChatMessages", "method": "GET", "path": "/v1/chats/{id}/messages", "group": "Chats", "summary": "Read a chat transcript", "description": "The chat's messages, oldest first: what the user asked, the agent's\nanswer text, a one-line summary of each step the agent took, the run\nprogress and the result table id when the turn produced creators. This\nis the same reader view a shared chat link shows; raw tool inputs and\noutputs are never returned.\n\nA chat with a search still running returns the transcript saved so\nfar. Pass `next_cursor` back as `cursor` to read the next page.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Chat id from GET /v1/chats. URL-encode it (MCP chat ids contain colons).", "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 50, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of messages, oldest first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Message id within the chat.", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "chat_message" ], "description": "", "constraints": [] }, { "name": "data.chat_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.role", "type": "enum", "required": false, "enum": [ "user", "assistant" ], "description": "", "constraints": [] }, { "name": "data.text", "type": "string", "required": false, "description": "The user's request, or the agent's answer text.", "constraints": [] }, { "name": "data.result_table_id", "type": "string | null", "required": false, "description": "The result table this turn produced, when it found creators.", "constraints": [] }, { "name": "data.steps", "type": "object[]", "required": false, "description": "One-line summaries of the steps the agent took during the turn. Raw tool inputs and outputs are never included.", "constraints": [] }, { "name": "data.steps.tool", "type": "string", "required": false, "description": "The step name, e.g. discover_creators.", "constraints": [] }, { "name": "data.steps.summary", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.progress", "type": "object | null", "required": false, "description": "Run progress for a sourcing turn (for example target, discovered, processed, kept, stop_reason); null otherwise.", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "id": "m1", "object": "chat_message", "chat_id": "conv_a", "role": "user", "text": "Find skincare creators in Austin", "result_table_id": null, "steps": [], "progress": null }, { "id": "m2", "object": "chat_message", "chat_id": "conv_a", "role": "assistant", "text": "Here are 12 creators.", "result_table_id": "table_1", "steps": [ { "tool": "discover_creators", "summary": "Searched 4 hashtags" } ], "progress": { "target": 12, "discovered": 80, "processed": 60, "kept": 12, "stop_reason": "target_reached" } } ], "has_more": false, "next_cursor": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] } ] }, { "name": "Creator CRM", "endpoints": [ { "id": "listCrmLeads", "method": "GET", "path": "/v1/leads", "group": "Creator CRM", "summary": "List CRM leads", "description": "Creators saved to the workspace's Creator CRM (the app's Saved Leads /\nCreator CRM tab): every creator kept across searches, automations and\nUGC Database unlocks, joined with their CRM record. Not the same thing\nas the members of an API list (`/v1/lists`).\n\nCreators the plan's view limit locks are never returned, exactly as\nthe CRM tab hides them (Ultra has no view limit);\nGET /v1/leads/pipeline reports how many as `locked_count`.\n\nA cursor is only valid with the same filters and sort; anything else\nanswers 400 `invalid_cursor`. Rate limit bucket `leads`: 240 requests\nper minute. Reads cost no leads and are not counted against the call\nquota.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] }, { "name": "stage", "in": "query", "required": false, "type": "string", "description": "One or more CRM stages, comma-separated or repeated: sourced, contacted, replied, negotiating, hired, creating, delivered, paid, declined.", "example": "replied,negotiating", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "tag", "in": "query", "required": false, "type": "string", "description": "Case-insensitive tag match.", "constraints": [ "max length 100" ] }, { "name": "list_id", "in": "query", "required": false, "type": "string", "description": "Only creators in this lead list (GET /v1/lead-lists).", "constraints": [] }, { "name": "has_email", "in": "query", "required": false, "type": "boolean", "description": "", "constraints": [] }, { "name": "search", "in": "query", "required": false, "type": "string", "description": "Matches handle, name, first name, email, niche, tags and note text, like the CRM search box.", "constraints": [ "max length 200" ] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "", "default": "last_activity", "enum": [ "last_activity", "name", "stage", "next_task", "deal_value", "followers", "fit_score" ], "constraints": [] }, { "name": "order", "in": "query", "required": false, "type": "enum", "description": "Defaults to asc for name, stage and next_task, desc otherwise.", "enum": [ "asc", "desc" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of CRM leads.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "data.first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "data.followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "data.rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "data.rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "data.rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "data.rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "data.rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "data.turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "data.sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "data.portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "data.stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "data.legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "data.tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "data.saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "data.outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "data.outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "data.crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "data.crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "data.crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "data.crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "data.crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "data.crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "data.crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "data.crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "lead", "id": "lead_3f2a9c0d1e4b5a6978c0d1e2", "platform": "instagram", "handle": "maya.makes", "name": "Maya Lopez", "first_name": "Maya", "followers": 4200, "email": "maya@example.com", "stage": "negotiating", "legacy_stage": "replied", "tags": [ "vip" ], "list_ids": [ "8c1b2f8e-5d0a-4b8e-9a43-2f6d1c0e7b11" ], "last_activity_at": "2026-10-07T09:12:00.000Z" } ], "has_more": true, "next_cursor": "eyJvIjoyNS4uLn0" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "createCrmLead", "method": "POST", "path": "/v1/leads", "group": "Creator CRM", "summary": "Save a creator to the CRM", "description": "Saves a creator from the UGC Database into the CRM through the app's\nown unlock, so the creator must already be in the UGC Database\n(otherwise 404 `creator_not_found`: run a creator search instead).\n\nCosts 1 lead from the monthly lead pool (the team owner's pool for\nteam members), exactly like unlocking in the app. Creators already\ndelivered to the workspace are never charged again. Plans that cannot\nunlock from the database get 402 `upgrade_required` with\n`required_plan` (`pro`). A used-up pool answers 402\n`lead_quota_exceeded`.\n\nOther errors: 409 `lead_already_saved` (the message names the\nexisting id), 409 `creator_previously_delivered` (delivered before,\nthen removed from the CRM; the app does not re-add it), 400\n`lead_list_not_found`, 503 `creator_database_unavailable` or\n`crm_write_failed` (nothing charged).\n\nSend an `Idempotency-Key` (1 to 255 visible characters) to make the\ncall safe to retry: a replay returns the stored lead with 200 and\n`Idempotency-Replayed: true`; the same key with a different body\nanswers 409 `idempotency_conflict`, and while the first call is still\nrunning 409 `idempotency_in_progress`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "platform", "type": "enum", "required": true, "enum": [ "instagram", "tiktok" ], "example": "instagram", "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": true, "example": "maya.makes", "description": "Creator handle; @ optional, case-insensitive.", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "example": [ "vip" ], "description": "Lowercased; duplicates rejected.", "constraints": [ "max 50 items" ] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Existing lead list ids.", "constraints": [ "max 50 items" ] } ], "example": { "platform": "instagram", "handle": "maya.makes", "stage": "sourced", "tags": [ "vip" ], "list_ids": [ "8c1b2f8e-5d0a-4b8e-9a43-2f6d1c0e7b11" ] } }, "response": { "code": "200", "description": "Idempotent replay of an earlier save.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace plan does not include this feature in the app either.\nerror.code is upgrade_required and error.required_plan names the\nlowest plan that unlocks it. Branch on error.code, not error.type.\nMessages never contain prices.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getCrmPipeline", "method": "GET", "path": "/v1/leads/pipeline", "group": "Creator CRM", "summary": "Get the pipeline summary", "description": "The CRM header strip and stage counts. `in_conversation` is replied +\nnegotiating; `working_with_you` is hired through paid;\n`committed_value` sums rate x deliverables on working creators, in\ntheir most common currency; `tasks_due` counts open tasks overdue or\ndue today (UTC day). `locked_count` is how many creators the plan's\nview limit hides.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "list_id", "in": "query", "required": false, "type": "string", "description": "Scope the summary to one lead list.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The pipeline summary.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead_pipeline" ], "description": "", "constraints": [] }, { "name": "list_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "total", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "locked_count", "type": "integer", "required": false, "description": "Creators hidden by the plan's view limit.", "constraints": [] }, { "name": "stages", "type": "object[]", "required": false, "description": "All nine stages in pipeline order.", "constraints": [] }, { "name": "stages.stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "stages.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "stages.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stages.deal_value", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "in_conversation", "type": "integer", "required": false, "description": "replied + negotiating.", "constraints": [] }, { "name": "working_with_you", "type": "integer", "required": false, "description": "hired, creating, delivered and paid.", "constraints": [] }, { "name": "committed_value", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "committed_value.amount", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "committed_value.currency", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "tasks_due", "type": "integer", "required": false, "description": "Open tasks overdue or due today (UTC).", "constraints": [] } ], "example": { "object": "lead_pipeline", "list_id": null, "total": 42, "locked_count": 0, "stages": [ { "stage": "sourced", "label": "Sourced", "count": 20, "deal_value": 0 }, { "stage": "negotiating", "label": "Negotiating", "count": 4, "deal_value": 1200 } ], "in_conversation": 6, "working_with_you": 9, "committed_value": { "amount": 4350, "currency": "USD" }, "tasks_due": 3 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getCrmLead", "method": "GET", "path": "/v1/leads/{id}", "group": "Creator CRM", "summary": "Retrieve a CRM lead", "description": "The creator with the full CRM record (deal terms, notes, tasks, timeline).", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ], "example": { "object": "lead", "id": "lead_3f2a9c0d1e4b5a6978c0d1e2", "platform": "instagram", "handle": "maya.makes", "name": "Maya Lopez", "first_name": "Maya", "profile_url": "https://www.instagram.com/maya.makes", "profile_picture_url": "https://app.ugcagent.app/api/avatar?url=...&h=maya.makes", "followers": 4200, "email": "maya@example.com", "bio": "UGC creator | skincare", "niche": "skincare", "location": "US", "portfolio_url": "https://maya.example", "links": [ "https://maya.example" ], "fit_score": 80, "stage": "negotiating", "legacy_stage": "replied", "tags": [ "vip" ], "list_ids": [ "8c1b2f8e-5d0a-4b8e-9a43-2f6d1c0e7b11" ], "saved_at": "2026-10-02T12:00:00.000Z", "last_activity_at": "2026-10-07T09:12:00.000Z", "outreach_syncs": [ { "provider": "instantly", "campaign_name": "Fall UGC", "synced_at": "2026-10-05T10:00:00.000Z" } ], "crm": { "stage_changed_at": "2026-10-07T09:12:00.000Z", "rate": 150, "currency": "USD", "deliverables": 3, "deal_value": 450, "rating": 4, "phone": "+1 555 0100", "last_contacted_at": "2026-10-06T15:00:00.000Z", "next_task": { "id": "t1", "title": "Send contract", "due_at": "2026-10-09T09:00:00.000Z", "done": false, "done_at": null, "created_at": "2026-10-07T09:00:00.000Z" }, "notes": [ { "id": "n1", "body": "Wants 6 months usage", "created_at": "2026-10-06T15:01:00.000Z", "updated_at": null } ], "tasks": [ { "id": "t1", "title": "Send contract", "due_at": "2026-10-09T09:00:00.000Z", "done": false, "done_at": null, "created_at": "2026-10-07T09:00:00.000Z" } ], "activity": [ { "id": "a3", "kind": "stage", "at": "2026-10-07T09:12:00.000Z", "text": "Moved to Negotiating", "from_stage": "replied", "to_stage": "negotiating", "channel": null } ] } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "updateCrmLead", "method": "PATCH", "path": "/v1/leads/{id}", "group": "Creator CRM", "summary": "Update a CRM lead", "description": "Moves a creator through the pipeline or edits deal terms, tags, lists\nand contact fields. Send at least one field (400 `empty_update`\notherwise). `tags` and `list_ids` replace the current values; every\nlist id must exist (400 `lead_list_not_found`). Changes go through the\nsame reducer as the app, so the timeline gets the same entries\n(\"Moved to Hired\", \"Rate set to $150 x 3 videos ($450)\"). Every stage\nwrite also sets `legacy_stage`. Accepts `Idempotency-Key`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "Replaces the current tags.", "constraints": [ "max 50 items" ] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Replaces list membership; each list must exist.", "constraints": [ "max 50 items" ] }, { "name": "first_name", "type": "string", "required": false, "description": "May be empty.", "constraints": [ "max length 80" ] }, { "name": "rate", "type": "number | null", "required": false, "example": 150, "description": "Rate per video; null clears.", "constraints": [ "min 0.01", "max 10000000" ] }, { "name": "currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "example": "USD", "description": "", "constraints": [] }, { "name": "deliverables", "type": "integer | null", "required": false, "example": 3, "description": "Number of videos; null clears.", "constraints": [ "min 1", "max 999" ] }, { "name": "rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "phone", "type": "string | null", "required": false, "description": "Empty string or null clears.", "constraints": [ "max length 40" ] } ], "example": { "stage": "hired", "rate": 150, "currency": "USD", "deliverables": 3 } }, "response": { "code": "200", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" } ] }, { "id": "deleteCrmLead", "method": "DELETE", "path": "/v1/leads/{id}", "group": "Creator CRM", "summary": "Remove a CRM lead", "description": "Removes the creator from the CRM, the same as deleting it in the app. Accepts `Idempotency-Key`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "204", "description": "Removed.", "fields": [], "example": null }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "addCrmLeadNote", "method": "POST", "path": "/v1/leads/{id}/notes", "group": "Creator CRM", "summary": "Add a note", "description": "Adds a private note to the creator's CRM record. The new note is last in `crm.notes`. Returns the updated lead. Accepts `Idempotency-Key`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "body", "type": "string", "required": true, "description": "", "constraints": [ "min length 1", "max length 4000" ] } ], "example": { "body": "Wants 6 months usage rights" } }, "response": { "code": "201", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "updateCrmLeadNote", "method": "PATCH", "path": "/v1/leads/{id}/notes/{note_id}", "group": "Creator CRM", "summary": "Edit a note", "description": "Replaces the note's text. 404 `note_not_found` when the note does not exist. Returns the updated lead.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "note_id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "body", "type": "string", "required": true, "description": "", "constraints": [ "min length 1", "max length 4000" ] } ] }, "response": { "code": "200", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "deleteCrmLeadNote", "method": "DELETE", "path": "/v1/leads/{id}/notes/{note_id}", "group": "Creator CRM", "summary": "Delete a note", "description": "Returns the updated lead. 404 `note_not_found` when the note does not exist.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "note_id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "addCrmLeadTask", "method": "POST", "path": "/v1/leads/{id}/tasks", "group": "Creator CRM", "summary": "Add a task", "description": "Adds a follow-up task. `due_at` takes a date (`YYYY-MM-DD`, meaning\n09:00 UTC that day), a full ISO 8601 timestamp, or null. Returns the\nupdated lead. Accepts `Idempotency-Key`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "title", "type": "string", "required": true, "example": "Send contract", "description": "", "constraints": [ "min length 1", "max length 200" ] }, { "name": "due_at", "type": "string | null", "required": false, "example": "2026-10-09", "description": "YYYY-MM-DD (09:00 UTC that day) or an ISO 8601 timestamp.", "constraints": [] } ], "example": { "title": "Send contract", "due_at": "2026-10-09" } }, "response": { "code": "201", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "updateCrmLeadTask", "method": "PATCH", "path": "/v1/leads/{id}/tasks/{task_id}", "group": "Creator CRM", "summary": "Complete or reopen a task", "description": "Sets `done`. Setting the current value is a no-op. 404 `task_not_found` when the task does not exist. Returns the updated lead.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "task_id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "done", "type": "boolean", "required": true, "description": "", "constraints": [] } ], "example": { "done": true } }, "response": { "code": "200", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "deleteCrmLeadTask", "method": "DELETE", "path": "/v1/leads/{id}/tasks/{task_id}", "group": "Creator CRM", "summary": "Delete a task", "description": "Returns the updated lead. 404 `task_not_found` when the task does not exist.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "task_id", "in": "path", "required": true, "type": "string", "description": "", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "logCrmLeadTouch", "method": "POST", "path": "/v1/leads/{id}/touches", "group": "Creator CRM", "summary": "Log an outreach touch", "description": "Records that you reached out (email, DM, call or other) and sets\n`crm.last_contacted_at`. The first touch on a `sourced` creator moves\nit to `contacted`, as in the app. Logging only: nothing is sent.\nReturns the updated lead. Accepts `Idempotency-Key`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "CRM lead id: lead_ + 24 hex characters, stable per creator.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "channel", "type": "enum", "required": true, "enum": [ "email", "dm", "call", "other" ], "example": "email", "description": "", "constraints": [] }, { "name": "text", "type": "string | null", "required": false, "description": "Optional detail for the timeline.", "constraints": [ "max length 500" ] } ], "example": { "channel": "email", "text": "Sent the brief" } }, "response": { "code": "201", "description": "The updated lead.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "lead_ + 24 hex characters, derived from platform + handle.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "Display name, falling back to first name or handle.", "constraints": [] }, { "name": "first_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Served through the app media cache (/api/avatar), never a raw expiring CDN link.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", null ], "description": "Estimated age band, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Verified UGC brand work with proof post URLs, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's post metrics (hit rate), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video in USD, from the creator's own rate card (not verified), for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "The creator's stated rates, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days, for creators unlocked from the UGC Database; otherwise null.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "Sample video URLs from their portfolio page, for creators unlocked from the UGC Database; otherwise empty.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "fit_score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stage", "type": "enum", "required": false, "enum": [ "sourced", "contacted", "replied", "negotiating", "hired", "creating", "delivered", "paid", "declined" ], "description": "Pipeline stage. declined is shown as \"Not a fit\" in the app.", "constraints": [] }, { "name": "legacy_stage", "type": "enum", "required": false, "enum": [ "new", "contacted", "replied", "booked" ], "description": "Coarse stage the CSV export and shared lists read; written alongside every stage change.", "constraints": [] }, { "name": "tags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "list_ids", "type": "string[]", "required": false, "description": "Lead lists this creator belongs to.", "constraints": [] }, { "name": "saved_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_activity_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs", "type": "object[]", "required": false, "description": "Outreach campaigns this creator was pushed to.", "constraints": [] }, { "name": "outreach_syncs.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "outreach_syncs.campaign_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "outreach_syncs.synced_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "crm.stage_changed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.rate", "type": "number | null", "required": false, "description": "Rate per video.", "constraints": [] }, { "name": "crm.currency", "type": "enum", "required": false, "enum": [ "USD", "EUR", "GBP", "CAD", "AUD" ], "description": "", "constraints": [] }, { "name": "crm.deliverables", "type": "integer | null", "required": false, "description": "Number of videos.", "constraints": [] }, { "name": "crm.deal_value", "type": "number | null", "required": false, "description": "rate x deliverables.", "constraints": [] }, { "name": "crm.rating", "type": "integer | null", "required": false, "description": "", "constraints": [ "min 1", "max 5" ] }, { "name": "crm.phone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.last_contacted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.next_task", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes", "type": "object[]", "required": false, "description": "Up to 200 notes.", "constraints": [] }, { "name": "crm.notes.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.body", "type": "string", "required": false, "description": "", "constraints": [ "max length 4000" ] }, { "name": "crm.notes.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.notes.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks", "type": "object[]", "required": false, "description": "Up to 200 tasks.", "constraints": [] }, { "name": "crm.tasks.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.title", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] }, { "name": "crm.tasks.due_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.done_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.tasks.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity", "type": "object[]", "required": false, "description": "Timeline, newest first, capped at 150 entries, including the derived saved and outreach-sync entries the app shows.", "constraints": [] }, { "name": "crm.activity.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.kind", "type": "enum", "required": false, "enum": [ "stage", "note", "task_added", "task_done", "touch", "field", "saved", "synced" ], "description": "", "constraints": [] }, { "name": "crm.activity.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.from_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.to_stage", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "crm.activity.channel", "type": "enum", "required": false, "enum": [ "email", "dm", "call", "other", null ], "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "exportCrmLeads", "method": "POST", "path": "/v1/lead-exports", "group": "Creator CRM", "summary": "Export CRM leads as CSV", "description": "Returns `text/csv` with the same columns as the app's CRM export:\nplatform, handle, profile_url, first_name, followers, email,\ndisplay_name, bio, portfolio_url, links, score, tags, stage,\ncrm_stage, rate, currency, videos, deal_value, fit_rating, next_task,\nnext_task_due, notes. Rows are sorted by last activity, newest first.\nNarrow it with `lead_ids` or the same filters as GET /v1/leads; an\nempty body exports every visible lead. The response carries\n`Content-Disposition: attachment` and `X-Lead-Count`.\n", "deprecated": false, "comingSoon": false, "params": [], "body": { "fields": [ { "name": "lead_ids", "type": "string[]", "required": false, "description": "Export only these leads.", "constraints": [ "min 1 items", "max 1000 items" ] }, { "name": "format", "type": "enum", "required": false, "default": "csv", "enum": [ "csv" ], "description": "", "constraints": [] }, { "name": "stage", "type": "string", "required": false, "description": "One or more stages, comma-separated.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "tag", "type": "string", "required": false, "description": "", "constraints": [ "max length 100" ] }, { "name": "list_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "has_email", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "search", "type": "string", "required": false, "description": "", "constraints": [ "max length 200" ] } ], "example": { "stage": "hired", "has_email": true } }, "response": { "code": "200", "description": "The CSV file.", "fields": [], "example": null }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "listCrmLeadLists", "method": "GET", "path": "/v1/lead-lists", "group": "Creator CRM", "summary": "List lead lists", "description": "The CRM's custom lists (the app's CRM sidebar), all on one page. Separate from API lists (`/v1/lists`).", "deprecated": false, "comingSoon": false, "params": [], "body": null, "response": { "code": "200", "description": "Every lead list.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "lead_list" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [ "max length 80" ] }, { "name": "data.lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "Always false.", "constraints": [] }, { "name": "next_cursor", "type": "null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "lead_list", "id": "8c1b2f8e-5d0a-4b8e-9a43-2f6d1c0e7b11", "name": "Fall drop", "lead_count": 12, "created_at": "2026-10-01T10:00:00.000Z", "updated_at": "2026-10-05T10:00:00.000Z" } ], "has_more": false, "next_cursor": null } }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "createCrmLeadList", "method": "POST", "path": "/v1/lead-lists", "group": "Creator CRM", "summary": "Create a lead list", "description": "Creates an empty CRM list. Add creators with PATCH /v1/leads/{id} `list_ids`. Accepts `Idempotency-Key` (a replay answers 200 with `Idempotency-Replayed: true`).", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "name", "type": "string", "required": true, "example": "Fall drop", "description": "", "constraints": [ "min length 1", "max length 80" ] } ], "example": { "name": "Fall drop" } }, "response": { "code": "200", "description": "Idempotent replay of an earlier create.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead_list" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [ "max length 80" ] }, { "name": "lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" } ] }, { "id": "getCrmLeadList", "method": "GET", "path": "/v1/lead-lists/{id}", "group": "Creator CRM", "summary": "Retrieve a lead list", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Lead list id.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The lead list.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead_list" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [ "max length 80" ] }, { "name": "lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "renameCrmLeadList", "method": "PATCH", "path": "/v1/lead-lists/{id}", "group": "Creator CRM", "summary": "Rename a lead list", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Lead list id.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "name", "type": "string", "required": true, "example": "Fall drop", "description": "", "constraints": [ "min length 1", "max length 80" ] } ] }, "response": { "code": "200", "description": "The renamed lead list.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead_list" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [ "max length 80" ] }, { "name": "lead_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "404", "description": "No resource with that id belongs to this workspace." } ] }, { "id": "deleteCrmLeadList", "method": "DELETE", "path": "/v1/lead-lists/{id}", "group": "Creator CRM", "summary": "Delete a lead list", "description": "Deletes the list and unlinks its members. Their CRM records stay.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Lead list id.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "404", "description": "No resource with that id belongs to this workspace." } ] } ] }, { "name": "UGC Database", "endpoints": [ { "id": "listDatabaseCreators", "method": "GET", "path": "/v1/database/creators", "group": "UGC Database", "summary": "Search the UGC Database", "description": "Browses the shared pool of already-sourced creators behind the app's\nUGC Database tab, with the same filters, sorting and masking. No\nsourcing job runs, it costs no leads and it is not counted against the\ncall quota. Rate limit: 120 requests per minute (bucket `database`).\n\nContact details stay masked until you unlock a creator: `email` is\nnull, `email_masked` shows the app's mask (for example\n`a••••@gmail.com`), emails and phone numbers in `bio` read\n`[email hidden]` / `[phone hidden]`, and contact links (mailto,\nWhatsApp, Telegram) are removed. Creators already delivered to you by\nany search, automation or earlier unlock come back with\n`unlocked: true` and the real address.\n\nProven UGC: `proven` lists the brands a creator verifiably made UGC\nfor (from the UGC Brands database), with video counts and views, and\n`performance` carries their hit rate (share of posts past 10K and 100K\nviews). Brand names and numbers show on every row; the proof post URLs\nand the posting account (`best_url`, `proof_urls`, `account_handle`)\nare null / empty until the creator is unlocked. Filter with\n`signal=proven`, `brand=`, `min_hit_rate=` and `min_median_views=`.\n\nStated rates: `rate_min_usd` and `rates` are the creator's own prices\nfrom their rate card or portfolio page (self-published, not verified),\nwith `turnaround_days` and `portfolio_brands` (past clients the page\nlists, also merged into `claimed_brands` and `brands_worked`). They\nshow on every row. `sample_videos` and `portfolio_pages` lead straight\nto the creator, so they are empty until the creator is unlocked. Filter\nwith `max_rate_usd=` or `signal=has_rates`, and sort with `rate_asc`.\n\nMulti-value filters accept repeated keys (`?niche=a&niche=b`) or a\ncomma list (`?niche=a,b`), at most 50 values of 60 characters each.\nUnknown parameters are rejected with `unknown_parameter`.\n\nCursors are offsets over a live snapshot that refreshes every few\nminutes, so a creator can move between pages after a refresh. A cursor\nis bound to the filters and sort it was issued for; reusing it with\ndifferent ones answers 400 `invalid_cursor`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "q", "in": "query", "required": false, "type": "string", "description": "Word-prefix match over handle, name, niche, labels and bio (ugc matches kit.ugc; care does not match skincare). A leading @ or # is ignored.", "constraints": [ "max length 120" ] }, { "name": "view", "in": "query", "required": false, "type": "enum", "description": "The app tabs. net_new: creators not yet delivered to you. unlocked: creators you can already see in full.", "default": "all", "enum": [ "all", "net_new", "unlocked" ], "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum[]", "description": "One or more platforms.", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "niche", "in": "query", "required": false, "type": "string[]", "description": "Niche labels or niche keys as returned by GET /v1/database/facets, lower case. A creator matches any of them. Values are split on commas.", "constraints": [] }, { "name": "exclude_niche", "in": "query", "required": false, "type": "string[]", "description": "Drop creators with any of these niches.", "constraints": [] }, { "name": "tier", "in": "query", "required": false, "type": "enum[]", "description": "Follower tiers: starter (under 1k), nano (1k to 9,999), micro (10k to 99,999), mid (100k to 499,999), macro (500k and up).", "enum": [ "starter", "nano", "micro", "mid", "macro" ], "constraints": [] }, { "name": "min_followers", "in": "query", "required": false, "type": "integer", "description": "Lowest follower count, inclusive. Must not exceed max_followers (invalid_follower_range).", "constraints": [ "min 0" ] }, { "name": "max_followers", "in": "query", "required": false, "type": "integer", "description": "Highest follower count, inclusive.", "constraints": [ "min 0" ] }, { "name": "country", "in": "query", "required": false, "type": "string[]", "description": "ISO 3166-1 alpha-2 codes, or unknown. GB is accepted and stored as UK.", "constraints": [] }, { "name": "region", "in": "query", "required": false, "type": "string[]", "description": "State or region the creator says they are based in, in English (Texas, England, Ontario, Community of Madrid), as listed in the region facet. Case-insensitive. Combine with country when a name exists in several countries.", "constraints": [] }, { "name": "city", "in": "query", "required": false, "type": "string[]", "description": "City the creator says they are based in, in English (Austin, London, Mexico City), as listed in the city facet. Case-insensitive. Combine with country when a name exists in several countries.", "constraints": [] }, { "name": "language", "in": "query", "required": false, "type": "string[]", "description": "Language values as returned in the language facet.", "constraints": [] }, { "name": "gender", "in": "query", "required": false, "type": "enum[]", "description": "Inferred gender, best effort.", "enum": [ "man", "woman", "unknown" ], "constraints": [] }, { "name": "age_band", "in": "query", "required": false, "type": "enum[]", "description": "Estimated age band, from profile photos, recent posts and bio. An estimate, not a verified age; unknown means no estimate.", "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", "unknown" ], "constraints": [] }, { "name": "email_kind", "in": "query", "required": false, "type": "enum[]", "description": "What kind of address the creator lists.", "enum": [ "personal", "creator_domain", "agency", "unknown" ], "constraints": [] }, { "name": "signal", "in": "query", "required": false, "type": "enum[]", "description": "All listed signals must match. ugc: UGC wording in handle, name or bio. portfolio: has a portfolio link. collabs: brand collaborations or collab wording. engagement: has engagement stats. untapped: no other brand has been delivered this creator. proven: verified UGC made for at least one brand (see proven). for_hire: says they take paid UGC work. has_rates: publishes their own rates (rate card or portfolio page).", "enum": [ "ugc", "portfolio", "collabs", "engagement", "untapped", "proven", "for_hire", "has_rates" ], "constraints": [] }, { "name": "added_within_days", "in": "query", "required": false, "type": "integer", "description": "Only creators added to the database within this many days.", "constraints": [ "min 1", "max 3650" ] }, { "name": "brand", "in": "query", "required": false, "type": "string[]", "description": "Worked with any of these brands, verified (proven) or named in their bio (claimed_brands), as listed in the brand facet. Case-insensitive.", "constraints": [] }, { "name": "min_hit_rate", "in": "query", "required": false, "type": "number", "description": "Minimum performance.hit_rate_10k: the share of posts with 10,000+ views, as a 0 to 1 fraction (0.25 = 25%). Creators without post metrics are excluded.", "constraints": [ "min 0", "max 1" ] }, { "name": "min_median_views", "in": "query", "required": false, "type": "integer", "description": "Minimum median views per post (performance.median_views, else engagement.median_views).", "constraints": [ "min 0" ] }, { "name": "portfolio_type", "in": "query", "required": false, "type": "enum[]", "description": "Where the creator keeps their portfolio, from their links.", "enum": [ "canva", "beacons", "linktree", "stan", "google_drive", "notion", "own_site", "other" ], "constraints": [] }, { "name": "creator_type", "in": "query", "required": false, "type": "enum[]", "description": "What kind of account this is, classified from the profile.", "enum": [ "ugc_creator", "influencer", "both", "business", "agency", "page", "other" ], "constraints": [] }, { "name": "service", "in": "query", "required": false, "type": "enum[]", "description": "Offers any of these services.", "enum": [ "ugc_video", "photo", "voiceover", "editing", "scriptwriting", "tiktok_shop", "whitelisting", "product_photography" ], "constraints": [] }, { "name": "on_camera", "in": "query", "required": false, "type": "enum[]", "description": "Whether the creator appears on camera in their recent posts.", "enum": [ "yes", "no", "mixed" ], "constraints": [] }, { "name": "setting", "in": "query", "required": false, "type": "enum[]", "description": "Where their recent posts are usually filmed.", "enum": [ "home", "kitchen", "bathroom", "bedroom", "outdoor", "car", "gym", "office", "studio", "store", "mixed" ], "constraints": [] }, { "name": "production", "in": "query", "required": false, "type": "enum[]", "description": "Production style of their recent posts.", "enum": [ "casual_phone", "polished", "professional" ], "constraints": [] }, { "name": "saturation", "in": "query", "required": false, "type": "enum[]", "description": "How many brands they already work with (brands_worked): fresh 0, low 1 to 2, medium 3 to 5, high 6 or more.", "enum": [ "fresh", "low", "medium", "high" ], "constraints": [] }, { "name": "max_rate_usd", "in": "query", "required": false, "type": "integer", "description": "Only creators whose lowest stated UGC video rate (rate_min_usd) is at or below this many US dollars. Creators who state no rate are excluded. Rates are self-published by the creator, not verified.", "constraints": [ "min 1", "max 1000000" ] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "Result order. fit sorts by fit_score, the app default. proven puts creators with verified UGC brand work first (most brands, then hit rate). hit_rate sorts by performance.hit_rate_10k, median_views by performance.median_views (falling back to engagement.median_views); rate_asc puts the lowest stated rate_min_usd first; creators without the metric sort last.", "default": "fit", "enum": [ "fit", "followers_desc", "followers_asc", "newest", "engagement", "name", "proven", "hit_rate", "median_views", "rate_asc" ], "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of creators.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "database_creator" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Database creator id.", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "Username without the @.", "constraints": [] }, { "name": "data.display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.profile_url", "type": "string | null", "required": false, "description": "Profile link.", "constraints": [] }, { "name": "data.profile_picture_url", "type": "string | null", "required": false, "description": "Avatar through the app's media cache, so it does not expire like raw Instagram and TikTok CDN links.", "constraints": [] }, { "name": "data.bio", "type": "string", "required": false, "description": "Profile bio. Emails and phone numbers read [email hidden] / [phone hidden] while locked.", "constraints": [] }, { "name": "data.niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.niche_labels", "type": "string[]", "required": false, "description": "Canonical niche labels.", "constraints": [] }, { "name": "data.followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.tier", "type": "enum", "required": false, "enum": [ "starter", "nano", "micro", "mid", "macro" ], "description": "", "constraints": [] }, { "name": "data.country", "type": "string | null", "required": false, "description": "ISO alpha-2 code (the United Kingdom is UK).", "constraints": [] }, { "name": "data.language", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "", "constraints": [] }, { "name": "data.age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", "unknown" ], "description": "Estimated age band from profile photos, recent posts and bio; unknown when there was no basis for an estimate.", "constraints": [] }, { "name": "data.region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, in English. Only set alongside the matching country.", "constraints": [] }, { "name": "data.city", "type": "string | null", "required": false, "description": "City the creator says they are based in, in English. Only set alongside the matching country.", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "The real address, only when unlocked.", "constraints": [] }, { "name": "data.email_masked", "type": "string | null", "required": false, "description": "The app's mask, for example a••••@gmail.com.", "constraints": [] }, { "name": "data.email_kind", "type": "enum", "required": false, "enum": [ "personal", "creator_domain", "agency", "unknown" ], "description": "", "constraints": [] }, { "name": "data.email_source", "type": "string | null", "required": false, "description": "Where the address was found.", "constraints": [] }, { "name": "data.links", "type": "string[]", "required": false, "description": "Bio links. Contact links are removed while locked.", "constraints": [] }, { "name": "data.portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.has_portfolio", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.ugc_signal", "type": "boolean", "required": false, "description": "UGC wording in handle, name or bio.", "constraints": [] }, { "name": "data.collab_signal", "type": "boolean", "required": false, "description": "Brand collaborations or collab wording.", "constraints": [] }, { "name": "data.brand_collabs", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.viral_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.posts_analyzed", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.proven", "type": "object | null", "required": false, "description": "Brands the creator verifiably made UGC for; null when none is known.", "constraints": [] }, { "name": "data.performance", "type": "object | null", "required": false, "description": "The creator's own post metrics; null when their posts have not been measured.", "constraints": [] }, { "name": "data.portfolio_type", "type": "enum", "required": false, "enum": [ "canva", "beacons", "linktree", "stan", "google_drive", "notion", "own_site", "other", null ], "description": "Where the creator keeps their portfolio, from their links; null without links.", "constraints": [] }, { "name": "data.creator_type", "type": "enum", "required": false, "enum": [ "ugc_creator", "influencer", "both", "business", "agency", "page", "other", null ], "description": "What kind of account this is; null until classified.", "constraints": [] }, { "name": "data.for_hire", "type": "boolean | null", "required": false, "description": "Says they take paid UGC work; null when unknown.", "constraints": [] }, { "name": "data.services", "type": "enum[]", "required": false, "enum": [ "ugc_video", "photo", "voiceover", "editing", "scriptwriting", "tiktok_shop", "whitelisting", "product_photography" ], "description": "", "constraints": [] }, { "name": "data.claimed_brands", "type": "string[]", "required": false, "description": "Brands the creator names in their bio (mentions, promo codes, worked-with lists). Not verified.", "constraints": [] }, { "name": "data.brands_worked", "type": "string[]", "required": false, "description": "Verified brand names (proven) first, then claimed ones.", "constraints": [] }, { "name": "data.saturation", "type": "enum", "required": false, "enum": [ "fresh", "low", "medium", "high" ], "description": "How many brands they already work with: fresh 0, low 1 to 2, medium 3 to 5, high 6 or more.", "constraints": [] }, { "name": "data.visual", "type": "object | null", "required": false, "description": "Content style from recent post thumbnails; null until classified.", "constraints": [] }, { "name": "data.visual.on_camera", "type": "enum", "required": false, "enum": [ "yes", "no", "mixed", null ], "description": "", "constraints": [] }, { "name": "data.visual.setting", "type": "enum", "required": false, "enum": [ "home", "kitchen", "bathroom", "bedroom", "outdoor", "car", "gym", "office", "studio", "store", "mixed", null ], "description": "", "constraints": [] }, { "name": "data.visual.production", "type": "enum", "required": false, "enum": [ "casual_phone", "polished", "professional", null ], "description": "", "constraints": [] }, { "name": "data.sub_niche", "type": "string | null", "required": false, "description": "Short free-text specialty, for example skincare for acne.", "constraints": [] }, { "name": "data.rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video, in USD, from the creator's own rate card or portfolio page. Self-published, not verified; null when none is stated.", "constraints": [] }, { "name": "data.rates", "type": "object[]", "required": false, "description": "Every price the creator states, up to 12. Self-published, not verified.", "constraints": [] }, { "name": "data.rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "data.rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "data.rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "data.rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "data.rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "data.portfolio_brands", "type": "string[]", "required": false, "description": "Past clients their portfolio page lists (claimed, not verified). Also merged into claimed_brands and brands_worked.", "constraints": [] }, { "name": "data.turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days; null when not stated.", "constraints": [] }, { "name": "data.sample_videos", "type": "string[]", "required": false, "description": "TikTok, Instagram or YouTube video URLs from their portfolio page, up to 6. Empty until the creator is unlocked.", "constraints": [] }, { "name": "data.portfolio_pages", "type": "object[]", "required": false, "description": "The link-in-bio, portfolio, media kit, rate card or website pages the rates were read from. Empty until the creator is unlocked.", "constraints": [] }, { "name": "data.portfolio_pages.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.portfolio_pages.kind", "type": "enum", "required": false, "enum": [ "link_in_bio", "portfolio", "media_kit", "rate_card", "own_site" ], "description": "", "constraints": [] }, { "name": "data.demand", "type": "enum", "required": false, "enum": [ "untapped", "low", "medium", "high" ], "description": "How many other brands were delivered this creator: untapped 0, low 1 to 2, medium 3 to 5, high 6 or more. Your own unlock is not counted.", "constraints": [] }, { "name": "data.fit_score", "type": "integer", "required": false, "description": "Score from public signals: UGC wording, portfolio, email kind, brand collabs, engagement, country, recency and bio length, plus a boost for verified UGC brand work, a 30%+ hit rate and a stated UGC video rate (capped at 100).", "constraints": [ "min 0", "max 100" ] }, { "name": "data.completeness", "type": "integer", "required": false, "description": "Share of profile fields present.", "constraints": [ "min 0", "max 100" ] }, { "name": "data.unlocked", "type": "boolean", "required": false, "description": "True when you can see the creator in full.", "constraints": [] }, { "name": "data.added_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "total_count", "type": "integer", "required": false, "description": "Creators matching the filters across all pages.", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "database_creator", "id": "4a30ae6c58106d121b34c29b174826b01bc28198ef159a71e16efe2a62f7bffa", "platform": "instagram", "handle": "anna.ugc", "display_name": "Anna | UGC", "profile_url": "https://instagram.com/anna.ugc", "profile_picture_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fscontent.cdninstagram.com%2Fv%2Fanna.jpg&h=anna.ugc", "bio": "UGC creator, skincare. Email: [email hidden]", "niche": "skincare", "niche_labels": [ "beauty" ], "followers": 20000, "tier": "micro", "country": "US", "region": "Texas", "city": "Austin", "language": "en", "gender": "woman", "age_band": "25_34", "email": null, "email_masked": "a••••@gmail.com", "email_kind": "personal", "email_source": "bio", "links": [ "https://anna.carrd.co" ], "portfolio_url": "https://anna.carrd.co", "has_portfolio": true, "ugc_signal": true, "collab_signal": true, "brand_collabs": [ "Glossier" ], "engagement": { "rate": 0.054, "median_views": 12000, "viral_score": 61, "posts_analyzed": 12 }, "proven": { "brand_count": 1, "brands": [ { "brand_id": "poppi", "name": "Poppi", "confidence": "confirmed", "platform": "tiktok", "brand_videos": 4, "median_views": 21000, "best_views": 180000, "last_brand_video_at": "2026-10-09T00:00:00.000Z", "account_handle": null, "best_url": null, "proof_urls": [] } ] }, "performance": { "posts": 40, "median_views": 12500, "hit_rate_10k": 0.55, "hit_rate_100k": 0.1, "posts_over_100k": 4, "posts_per_week": 3.3, "last_posted_at": "2026-10-11T00:00:00.000Z" }, "portfolio_type": "own_site", "creator_type": "ugc_creator", "for_hire": true, "services": [ "ugc_video", "voiceover" ], "claimed_brands": [ "Glossier" ], "brands_worked": [ "Poppi", "Glossier" ], "saturation": "low", "visual": { "on_camera": "yes", "setting": "kitchen", "production": "casual_phone" }, "sub_niche": "skincare for acne", "rate_min_usd": 150, "rates": [ { "item": "1 UGC video", "price": 150, "currency": "USD", "usd": 150, "unit": "per_video" }, { "item": "3 video bundle", "price": 400, "currency": "USD", "usd": 400, "unit": "package" } ], "portfolio_brands": [ "Glossier" ], "turnaround_days": 5, "sample_videos": [], "portfolio_pages": [], "demand": "low", "fit_score": 85, "completeness": 90, "unlocked": false, "added_at": "2026-10-02T09:12:00.000Z", "refreshed_at": "2026-10-02T09:12:00.000Z" } ], "has_more": true, "next_cursor": "eyJvIjoyNSwiaCI6IjRrUzF6In0", "total_count": 1834 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getDatabaseCreator", "method": "GET", "path": "/v1/database/creators/{id}", "group": "UGC Database", "summary": "Retrieve a database creator", "description": "One creator's full profile. The email and unredacted bio and links are\nincluded only when the creator is unlocked for you (unlocked through\nthis API or the app, or delivered by an earlier search or\nautomation). Accepts no query parameters. Missing creators answer 404\n`database_creator_not_found`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Database creator id, from GET /v1/database/creators.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The creator.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "database_creator" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Database creator id.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "Username without the @.", "constraints": [] }, { "name": "display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "profile_url", "type": "string | null", "required": false, "description": "Profile link.", "constraints": [] }, { "name": "profile_picture_url", "type": "string | null", "required": false, "description": "Avatar through the app's media cache, so it does not expire like raw Instagram and TikTok CDN links.", "constraints": [] }, { "name": "bio", "type": "string", "required": false, "description": "Profile bio. Emails and phone numbers read [email hidden] / [phone hidden] while locked.", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "niche_labels", "type": "string[]", "required": false, "description": "Canonical niche labels.", "constraints": [] }, { "name": "followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "tier", "type": "enum", "required": false, "enum": [ "starter", "nano", "micro", "mid", "macro" ], "description": "", "constraints": [] }, { "name": "country", "type": "string | null", "required": false, "description": "ISO alpha-2 code (the United Kingdom is UK).", "constraints": [] }, { "name": "language", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "", "constraints": [] }, { "name": "age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", "unknown" ], "description": "Estimated age band from profile photos, recent posts and bio; unknown when there was no basis for an estimate.", "constraints": [] }, { "name": "region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, in English. Only set alongside the matching country.", "constraints": [] }, { "name": "city", "type": "string | null", "required": false, "description": "City the creator says they are based in, in English. Only set alongside the matching country.", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "The real address, only when unlocked.", "constraints": [] }, { "name": "email_masked", "type": "string | null", "required": false, "description": "The app's mask, for example a••••@gmail.com.", "constraints": [] }, { "name": "email_kind", "type": "enum", "required": false, "enum": [ "personal", "creator_domain", "agency", "unknown" ], "description": "", "constraints": [] }, { "name": "email_source", "type": "string | null", "required": false, "description": "Where the address was found.", "constraints": [] }, { "name": "links", "type": "string[]", "required": false, "description": "Bio links. Contact links are removed while locked.", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "has_portfolio", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "ugc_signal", "type": "boolean", "required": false, "description": "UGC wording in handle, name or bio.", "constraints": [] }, { "name": "collab_signal", "type": "boolean", "required": false, "description": "Brand collaborations or collab wording.", "constraints": [] }, { "name": "brand_collabs", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "engagement", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "engagement.rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "engagement.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "engagement.viral_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "engagement.posts_analyzed", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "proven", "type": "object | null", "required": false, "description": "Brands the creator verifiably made UGC for; null when none is known.", "constraints": [] }, { "name": "performance", "type": "object | null", "required": false, "description": "The creator's own post metrics; null when their posts have not been measured.", "constraints": [] }, { "name": "portfolio_type", "type": "enum", "required": false, "enum": [ "canva", "beacons", "linktree", "stan", "google_drive", "notion", "own_site", "other", null ], "description": "Where the creator keeps their portfolio, from their links; null without links.", "constraints": [] }, { "name": "creator_type", "type": "enum", "required": false, "enum": [ "ugc_creator", "influencer", "both", "business", "agency", "page", "other", null ], "description": "What kind of account this is; null until classified.", "constraints": [] }, { "name": "for_hire", "type": "boolean | null", "required": false, "description": "Says they take paid UGC work; null when unknown.", "constraints": [] }, { "name": "services", "type": "enum[]", "required": false, "enum": [ "ugc_video", "photo", "voiceover", "editing", "scriptwriting", "tiktok_shop", "whitelisting", "product_photography" ], "description": "", "constraints": [] }, { "name": "claimed_brands", "type": "string[]", "required": false, "description": "Brands the creator names in their bio (mentions, promo codes, worked-with lists). Not verified.", "constraints": [] }, { "name": "brands_worked", "type": "string[]", "required": false, "description": "Verified brand names (proven) first, then claimed ones.", "constraints": [] }, { "name": "saturation", "type": "enum", "required": false, "enum": [ "fresh", "low", "medium", "high" ], "description": "How many brands they already work with: fresh 0, low 1 to 2, medium 3 to 5, high 6 or more.", "constraints": [] }, { "name": "visual", "type": "object | null", "required": false, "description": "Content style from recent post thumbnails; null until classified.", "constraints": [] }, { "name": "visual.on_camera", "type": "enum", "required": false, "enum": [ "yes", "no", "mixed", null ], "description": "", "constraints": [] }, { "name": "visual.setting", "type": "enum", "required": false, "enum": [ "home", "kitchen", "bathroom", "bedroom", "outdoor", "car", "gym", "office", "studio", "store", "mixed", null ], "description": "", "constraints": [] }, { "name": "visual.production", "type": "enum", "required": false, "enum": [ "casual_phone", "polished", "professional", null ], "description": "", "constraints": [] }, { "name": "sub_niche", "type": "string | null", "required": false, "description": "Short free-text specialty, for example skincare for acne.", "constraints": [] }, { "name": "rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video, in USD, from the creator's own rate card or portfolio page. Self-published, not verified; null when none is stated.", "constraints": [] }, { "name": "rates", "type": "object[]", "required": false, "description": "Every price the creator states, up to 12. Self-published, not verified.", "constraints": [] }, { "name": "rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "portfolio_brands", "type": "string[]", "required": false, "description": "Past clients their portfolio page lists (claimed, not verified). Also merged into claimed_brands and brands_worked.", "constraints": [] }, { "name": "turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days; null when not stated.", "constraints": [] }, { "name": "sample_videos", "type": "string[]", "required": false, "description": "TikTok, Instagram or YouTube video URLs from their portfolio page, up to 6. Empty until the creator is unlocked.", "constraints": [] }, { "name": "portfolio_pages", "type": "object[]", "required": false, "description": "The link-in-bio, portfolio, media kit, rate card or website pages the rates were read from. Empty until the creator is unlocked.", "constraints": [] }, { "name": "portfolio_pages.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "portfolio_pages.kind", "type": "enum", "required": false, "enum": [ "link_in_bio", "portfolio", "media_kit", "rate_card", "own_site" ], "description": "", "constraints": [] }, { "name": "demand", "type": "enum", "required": false, "enum": [ "untapped", "low", "medium", "high" ], "description": "How many other brands were delivered this creator: untapped 0, low 1 to 2, medium 3 to 5, high 6 or more. Your own unlock is not counted.", "constraints": [] }, { "name": "fit_score", "type": "integer", "required": false, "description": "Score from public signals: UGC wording, portfolio, email kind, brand collabs, engagement, country, recency and bio length, plus a boost for verified UGC brand work, a 30%+ hit rate and a stated UGC video rate (capped at 100).", "constraints": [ "min 0", "max 100" ] }, { "name": "completeness", "type": "integer", "required": false, "description": "Share of profile fields present.", "constraints": [ "min 0", "max 100" ] }, { "name": "unlocked", "type": "boolean", "required": false, "description": "True when you can see the creator in full.", "constraints": [] }, { "name": "added_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getDatabaseFacets", "method": "GET", "path": "/v1/database/facets", "group": "UGC Database", "summary": "Get database facets", "description": "Counts per filter value for the creators matching the same filters as\nGET /v1/database/creators (no `sort`, `limit` or `cursor`). Each facet\nignores its own selection, so its counts show what picking another\nvalue would return, exactly like the app's filter rail. Use it to\ndiscover valid `niche`, `country` and `language` values.\n\nAlso returns pool insights for the match and your `access`: plan,\nwhether you can unlock, and leads left this month. Facet lists are\ncapped at 300 niches, 120 countries and 60 languages. Costs no leads\nand is not counted against the call quota.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "q", "in": "query", "required": false, "type": "string", "description": "Word-prefix match over handle, name, niche, labels and bio (ugc matches kit.ugc; care does not match skincare). A leading @ or # is ignored.", "constraints": [ "max length 120" ] }, { "name": "view", "in": "query", "required": false, "type": "enum", "description": "The app tabs. net_new: creators not yet delivered to you. unlocked: creators you can already see in full.", "default": "all", "enum": [ "all", "net_new", "unlocked" ], "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum[]", "description": "One or more platforms.", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "niche", "in": "query", "required": false, "type": "string[]", "description": "Niche labels or niche keys as returned by GET /v1/database/facets, lower case. A creator matches any of them. Values are split on commas.", "constraints": [] }, { "name": "exclude_niche", "in": "query", "required": false, "type": "string[]", "description": "Drop creators with any of these niches.", "constraints": [] }, { "name": "tier", "in": "query", "required": false, "type": "enum[]", "description": "Follower tiers: starter (under 1k), nano (1k to 9,999), micro (10k to 99,999), mid (100k to 499,999), macro (500k and up).", "enum": [ "starter", "nano", "micro", "mid", "macro" ], "constraints": [] }, { "name": "min_followers", "in": "query", "required": false, "type": "integer", "description": "Lowest follower count, inclusive. Must not exceed max_followers (invalid_follower_range).", "constraints": [ "min 0" ] }, { "name": "max_followers", "in": "query", "required": false, "type": "integer", "description": "Highest follower count, inclusive.", "constraints": [ "min 0" ] }, { "name": "country", "in": "query", "required": false, "type": "string[]", "description": "ISO 3166-1 alpha-2 codes, or unknown. GB is accepted and stored as UK.", "constraints": [] }, { "name": "region", "in": "query", "required": false, "type": "string[]", "description": "State or region the creator says they are based in, in English (Texas, England, Ontario, Community of Madrid), as listed in the region facet. Case-insensitive. Combine with country when a name exists in several countries.", "constraints": [] }, { "name": "city", "in": "query", "required": false, "type": "string[]", "description": "City the creator says they are based in, in English (Austin, London, Mexico City), as listed in the city facet. Case-insensitive. Combine with country when a name exists in several countries.", "constraints": [] }, { "name": "language", "in": "query", "required": false, "type": "string[]", "description": "Language values as returned in the language facet.", "constraints": [] }, { "name": "gender", "in": "query", "required": false, "type": "enum[]", "description": "Inferred gender, best effort.", "enum": [ "man", "woman", "unknown" ], "constraints": [] }, { "name": "age_band", "in": "query", "required": false, "type": "enum[]", "description": "Estimated age band, from profile photos, recent posts and bio. An estimate, not a verified age; unknown means no estimate.", "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", "unknown" ], "constraints": [] }, { "name": "email_kind", "in": "query", "required": false, "type": "enum[]", "description": "What kind of address the creator lists.", "enum": [ "personal", "creator_domain", "agency", "unknown" ], "constraints": [] }, { "name": "signal", "in": "query", "required": false, "type": "enum[]", "description": "All listed signals must match. ugc: UGC wording in handle, name or bio. portfolio: has a portfolio link. collabs: brand collaborations or collab wording. engagement: has engagement stats. untapped: no other brand has been delivered this creator. proven: verified UGC made for at least one brand (see proven). for_hire: says they take paid UGC work. has_rates: publishes their own rates (rate card or portfolio page).", "enum": [ "ugc", "portfolio", "collabs", "engagement", "untapped", "proven", "for_hire", "has_rates" ], "constraints": [] }, { "name": "added_within_days", "in": "query", "required": false, "type": "integer", "description": "Only creators added to the database within this many days.", "constraints": [ "min 1", "max 3650" ] }, { "name": "brand", "in": "query", "required": false, "type": "string[]", "description": "Worked with any of these brands, verified (proven) or named in their bio (claimed_brands), as listed in the brand facet. Case-insensitive.", "constraints": [] }, { "name": "min_hit_rate", "in": "query", "required": false, "type": "number", "description": "Minimum performance.hit_rate_10k: the share of posts with 10,000+ views, as a 0 to 1 fraction (0.25 = 25%). Creators without post metrics are excluded.", "constraints": [ "min 0", "max 1" ] }, { "name": "min_median_views", "in": "query", "required": false, "type": "integer", "description": "Minimum median views per post (performance.median_views, else engagement.median_views).", "constraints": [ "min 0" ] }, { "name": "portfolio_type", "in": "query", "required": false, "type": "enum[]", "description": "Where the creator keeps their portfolio, from their links.", "enum": [ "canva", "beacons", "linktree", "stan", "google_drive", "notion", "own_site", "other" ], "constraints": [] }, { "name": "creator_type", "in": "query", "required": false, "type": "enum[]", "description": "What kind of account this is, classified from the profile.", "enum": [ "ugc_creator", "influencer", "both", "business", "agency", "page", "other" ], "constraints": [] }, { "name": "service", "in": "query", "required": false, "type": "enum[]", "description": "Offers any of these services.", "enum": [ "ugc_video", "photo", "voiceover", "editing", "scriptwriting", "tiktok_shop", "whitelisting", "product_photography" ], "constraints": [] }, { "name": "on_camera", "in": "query", "required": false, "type": "enum[]", "description": "Whether the creator appears on camera in their recent posts.", "enum": [ "yes", "no", "mixed" ], "constraints": [] }, { "name": "setting", "in": "query", "required": false, "type": "enum[]", "description": "Where their recent posts are usually filmed.", "enum": [ "home", "kitchen", "bathroom", "bedroom", "outdoor", "car", "gym", "office", "studio", "store", "mixed" ], "constraints": [] }, { "name": "production", "in": "query", "required": false, "type": "enum[]", "description": "Production style of their recent posts.", "enum": [ "casual_phone", "polished", "professional" ], "constraints": [] }, { "name": "saturation", "in": "query", "required": false, "type": "enum[]", "description": "How many brands they already work with (brands_worked): fresh 0, low 1 to 2, medium 3 to 5, high 6 or more.", "enum": [ "fresh", "low", "medium", "high" ], "constraints": [] }, { "name": "max_rate_usd", "in": "query", "required": false, "type": "integer", "description": "Only creators whose lowest stated UGC video rate (rate_min_usd) is at or below this many US dollars. Creators who state no rate are excluded. Rates are self-published by the creator, not verified.", "constraints": [ "min 1", "max 1000000" ] } ], "body": null, "response": { "code": "200", "description": "Facet counts, insights and access.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "database_facets" ], "description": "", "constraints": [] }, { "name": "loaded_at", "type": "string | null", "required": false, "description": "When the snapshot was last loaded.", "constraints": [] }, { "name": "total_indexed", "type": "integer", "required": false, "description": "Creators in the database.", "constraints": [] }, { "name": "matched", "type": "integer", "required": false, "description": "Creators matching the filters.", "constraints": [] }, { "name": "views", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "views.all", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "views.net_new", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "views.unlocked", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets", "type": "object", "required": false, "description": "Value counts per filter. Each facet ignores its own selection.", "constraints": [] }, { "name": "facets.platform", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.platform.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.platform.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.niche", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.niche.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.niche.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.tier", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.tier.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.tier.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.country", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.country.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.country.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.region", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.region.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.region.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.city", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.city.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.city.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.language", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.language.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.language.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.gender", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.gender.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.gender.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.age_band", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.age_band.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.age_band.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.email_kind", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.email_kind.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.email_kind.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.signal", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.signal.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.signal.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.brand", "type": "object[]", "required": false, "description": "Brands worked with (verified and claimed), up to 300.", "constraints": [] }, { "name": "facets.brand.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.brand.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.portfolio_type", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.portfolio_type.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.portfolio_type.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.creator_type", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.creator_type.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.creator_type.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.service", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.service.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.service.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.on_camera", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.on_camera.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.on_camera.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.setting", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.setting.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.setting.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.production", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.production.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.production.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "facets.saturation", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "facets.saturation.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "facets.saturation.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "insights", "type": "object", "required": false, "description": "Market snapshot of the matched creators.", "constraints": [] }, { "name": "insights.matched", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "insights.with_personal_email_pct", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "insights.portfolio_pct", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "insights.ugc_pct", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "insights.collab_pct", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "insights.proven_pct", "type": "number", "required": false, "description": "Share with verified UGC brand work.", "constraints": [] }, { "name": "insights.rates_pct", "type": "number", "required": false, "description": "Share that publish their own rates.", "constraints": [] }, { "name": "insights.median_rate_usd", "type": "integer | null", "required": false, "description": "Median of rate_min_usd among the matched creators who state one; null when none do.", "constraints": [] }, { "name": "insights.median_followers", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "insights.added_30d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "insights.avg_fit", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "insights.tier_mix", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "insights.tier_mix.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "insights.tier_mix.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "insights.platform_mix", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "insights.platform_mix.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "insights.platform_mix.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "insights.top_niches", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "insights.top_niches.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "insights.top_niches.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "insights.top_countries", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "insights.top_countries.value", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "insights.top_countries.count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "access", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "access.object", "type": "enum", "required": false, "enum": [ "database_access" ], "description": "", "constraints": [] }, { "name": "access.plan", "type": "string", "required": false, "description": "The plan in effect, inherited from the team owner for team members.", "constraints": [] }, { "name": "access.can_unlock", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "access.leads_remaining", "type": "integer | null", "required": false, "description": "Leads left this month; null when the pool is unlimited.", "constraints": [] }, { "name": "access.monthly_lead_limit", "type": "integer | null", "required": false, "description": "Monthly lead pool; null when unlimited.", "constraints": [] } ], "example": { "object": "database_facets", "loaded_at": "2026-10-07T10:00:00.000Z", "total_indexed": 28241, "matched": 1834, "views": { "all": 1834, "net_new": 1790, "unlocked": 44 }, "facets": { "platform": [ { "value": "instagram", "count": 1500 }, { "value": "tiktok", "count": 334 } ], "niche": [ { "value": "beauty", "count": 900 } ], "tier": [ { "value": "micro", "count": 700 } ], "country": [ { "value": "US", "count": 800 }, { "value": "UNKNOWN", "count": 120 } ], "region": [ { "value": "Texas", "count": 140 }, { "value": "California", "count": 120 } ], "city": [ { "value": "Austin", "count": 30 }, { "value": "Los Angeles", "count": 28 } ], "language": [ { "value": "en", "count": 1500 } ], "gender": [ { "value": "woman", "count": 1300 } ], "age_band": [ { "value": "25_34", "count": 520 }, { "value": "unknown", "count": 900 } ], "email_kind": [ { "value": "personal", "count": 1600 } ], "signal": [ { "value": "ugc", "count": 600 }, { "value": "untapped", "count": 1200 }, { "value": "proven", "count": 140 }, { "value": "for_hire", "count": 410 } ], "brand": [ { "value": "Poppi", "count": 22 }, { "value": "Cal AI", "count": 18 } ], "portfolio_type": [ { "value": "canva", "count": 210 }, { "value": "linktree", "count": 160 } ], "creator_type": [ { "value": "ugc_creator", "count": 700 }, { "value": "influencer", "count": 400 } ], "service": [ { "value": "ugc_video", "count": 650 }, { "value": "photo", "count": 300 } ], "on_camera": [ { "value": "yes", "count": 900 } ], "setting": [ { "value": "home", "count": 500 }, { "value": "kitchen", "count": 120 } ], "production": [ { "value": "casual_phone", "count": 800 } ], "saturation": [ { "value": "fresh", "count": 1300 }, { "value": "low", "count": 400 } ] }, "insights": { "matched": 1834, "with_personal_email_pct": 87.2, "portfolio_pct": 21.4, "ugc_pct": 33.1, "collab_pct": 27.9, "proven_pct": 7.6, "rates_pct": 12.4, "median_rate_usd": 150, "median_followers": 8200, "added_30d": 410, "avg_fit": 52, "tier_mix": [ { "value": "micro", "count": 700 } ], "platform_mix": [ { "value": "instagram", "count": 1500 } ], "top_niches": [ { "value": "beauty", "count": 900 } ], "top_countries": [ { "value": "US", "count": 800 } ] }, "access": { "object": "database_access", "plan": "ultra", "can_unlock": true, "leads_remaining": null, "monthly_lead_limit": null } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "createDatabaseUnlock", "method": "POST", "path": "/v1/database/unlocks", "group": "UGC Database", "summary": "Unlock creators", "description": "Reveals the email of 1 to 100 database creators and saves them to your\nCreator CRM (the app's Saved Leads), through the same function as the\napp's Unlock button. Duplicate ids are collapsed.\n\nBilling: 1 lead from the workspace's monthly lead pool per creator\nnewly unlocked, exactly as in the app. Creators already delivered to\nyou are returned in `already_unlocked_ids` and not charged. If the\nbatch needs more leads than remain, the call answers 402\n`lead_quota_exceeded` and nothing is charged. Not counted against the\nAPI call quota. Team members draw from the team owner's pool, like the\napp.\n\nPlan gate: unlocking needs a plan with unlock rights (Pro and above in\nthe app). Otherwise 402 `upgrade_required` with\n`error.required_plan`.\n\nSend an `Idempotency-Key` to make retries safe: the same key with the\nsame body returns the stored result with `Idempotency-Replayed: true`;\na different body answers 409 `idempotency_conflict`. Concurrent\nduplicate unlocks charge once.\n\nOther outcomes: 404 `database_creators_not_found` when none of the ids\nexist; 503 `unlock_save_failed` when the creators could not be saved\n(nothing charged, retry). Unlocks do not emit webhook events.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "creator_ids", "type": "string[]", "required": true, "example": [ "4a30ae6c58106d121b34c29b174826b01bc28198ef159a71e16efe2a62f7bffa" ], "description": "Database creator ids to unlock. Duplicates are collapsed.", "constraints": [ "min 1 items", "max 100 items" ] } ], "example": { "creator_ids": [ "4a30ae6c58106d121b34c29b174826b01bc28198ef159a71e16efe2a62f7bffa" ] } }, "response": { "code": "200", "description": "The unlock result. Replays carry Idempotency-Replayed: true.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "database_unlock" ], "description": "", "constraints": [] }, { "name": "charged_leads", "type": "integer", "required": false, "description": "Leads taken from the monthly pool by this call.", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "Every requested creator now visible in full (newly and previously unlocked).", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "database_creator" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Database creator id.", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "Username without the @.", "constraints": [] }, { "name": "data.display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.profile_url", "type": "string | null", "required": false, "description": "Profile link.", "constraints": [] }, { "name": "data.profile_picture_url", "type": "string | null", "required": false, "description": "Avatar through the app's media cache, so it does not expire like raw Instagram and TikTok CDN links.", "constraints": [] }, { "name": "data.bio", "type": "string", "required": false, "description": "Profile bio. Emails and phone numbers read [email hidden] / [phone hidden] while locked.", "constraints": [] }, { "name": "data.niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.niche_labels", "type": "string[]", "required": false, "description": "Canonical niche labels.", "constraints": [] }, { "name": "data.followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.tier", "type": "enum", "required": false, "enum": [ "starter", "nano", "micro", "mid", "macro" ], "description": "", "constraints": [] }, { "name": "data.country", "type": "string | null", "required": false, "description": "ISO alpha-2 code (the United Kingdom is UK).", "constraints": [] }, { "name": "data.language", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.gender", "type": "enum", "required": false, "enum": [ "man", "woman", "unknown" ], "description": "", "constraints": [] }, { "name": "data.age_band", "type": "enum", "required": false, "enum": [ "under_18", "18_24", "25_34", "35_44", "45_54", "55_plus", "unknown" ], "description": "Estimated age band from profile photos, recent posts and bio; unknown when there was no basis for an estimate.", "constraints": [] }, { "name": "data.region", "type": "string | null", "required": false, "description": "State or region the creator says they are based in, in English. Only set alongside the matching country.", "constraints": [] }, { "name": "data.city", "type": "string | null", "required": false, "description": "City the creator says they are based in, in English. Only set alongside the matching country.", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "The real address, only when unlocked.", "constraints": [] }, { "name": "data.email_masked", "type": "string | null", "required": false, "description": "The app's mask, for example a••••@gmail.com.", "constraints": [] }, { "name": "data.email_kind", "type": "enum", "required": false, "enum": [ "personal", "creator_domain", "agency", "unknown" ], "description": "", "constraints": [] }, { "name": "data.email_source", "type": "string | null", "required": false, "description": "Where the address was found.", "constraints": [] }, { "name": "data.links", "type": "string[]", "required": false, "description": "Bio links. Contact links are removed while locked.", "constraints": [] }, { "name": "data.portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.has_portfolio", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.ugc_signal", "type": "boolean", "required": false, "description": "UGC wording in handle, name or bio.", "constraints": [] }, { "name": "data.collab_signal", "type": "boolean", "required": false, "description": "Brand collaborations or collab wording.", "constraints": [] }, { "name": "data.brand_collabs", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.viral_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement.posts_analyzed", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.proven", "type": "object | null", "required": false, "description": "Brands the creator verifiably made UGC for; null when none is known.", "constraints": [] }, { "name": "data.performance", "type": "object | null", "required": false, "description": "The creator's own post metrics; null when their posts have not been measured.", "constraints": [] }, { "name": "data.portfolio_type", "type": "enum", "required": false, "enum": [ "canva", "beacons", "linktree", "stan", "google_drive", "notion", "own_site", "other", null ], "description": "Where the creator keeps their portfolio, from their links; null without links.", "constraints": [] }, { "name": "data.creator_type", "type": "enum", "required": false, "enum": [ "ugc_creator", "influencer", "both", "business", "agency", "page", "other", null ], "description": "What kind of account this is; null until classified.", "constraints": [] }, { "name": "data.for_hire", "type": "boolean | null", "required": false, "description": "Says they take paid UGC work; null when unknown.", "constraints": [] }, { "name": "data.services", "type": "enum[]", "required": false, "enum": [ "ugc_video", "photo", "voiceover", "editing", "scriptwriting", "tiktok_shop", "whitelisting", "product_photography" ], "description": "", "constraints": [] }, { "name": "data.claimed_brands", "type": "string[]", "required": false, "description": "Brands the creator names in their bio (mentions, promo codes, worked-with lists). Not verified.", "constraints": [] }, { "name": "data.brands_worked", "type": "string[]", "required": false, "description": "Verified brand names (proven) first, then claimed ones.", "constraints": [] }, { "name": "data.saturation", "type": "enum", "required": false, "enum": [ "fresh", "low", "medium", "high" ], "description": "How many brands they already work with: fresh 0, low 1 to 2, medium 3 to 5, high 6 or more.", "constraints": [] }, { "name": "data.visual", "type": "object | null", "required": false, "description": "Content style from recent post thumbnails; null until classified.", "constraints": [] }, { "name": "data.visual.on_camera", "type": "enum", "required": false, "enum": [ "yes", "no", "mixed", null ], "description": "", "constraints": [] }, { "name": "data.visual.setting", "type": "enum", "required": false, "enum": [ "home", "kitchen", "bathroom", "bedroom", "outdoor", "car", "gym", "office", "studio", "store", "mixed", null ], "description": "", "constraints": [] }, { "name": "data.visual.production", "type": "enum", "required": false, "enum": [ "casual_phone", "polished", "professional", null ], "description": "", "constraints": [] }, { "name": "data.sub_niche", "type": "string | null", "required": false, "description": "Short free-text specialty, for example skincare for acne.", "constraints": [] }, { "name": "data.rate_min_usd", "type": "integer | null", "required": false, "description": "Lowest stated price for one UGC video, in USD, from the creator's own rate card or portfolio page. Self-published, not verified; null when none is stated.", "constraints": [] }, { "name": "data.rates", "type": "object[]", "required": false, "description": "Every price the creator states, up to 12. Self-published, not verified.", "constraints": [] }, { "name": "data.rates.item", "type": "string", "required": false, "description": "What the price is for, as the creator words it (for example 1 UGC video).", "constraints": [] }, { "name": "data.rates.price", "type": "number", "required": false, "description": "In the stated currency.", "constraints": [] }, { "name": "data.rates.currency", "type": "string", "required": false, "description": "ISO 4217 code, for example USD, GBP, EUR.", "constraints": [] }, { "name": "data.rates.usd", "type": "number | null", "required": false, "description": "The price in USD; null when it could not be converted.", "constraints": [] }, { "name": "data.rates.unit", "type": "enum", "required": false, "enum": [ "per_video", "per_photo", "package", "per_month", "other" ], "description": "", "constraints": [] }, { "name": "data.portfolio_brands", "type": "string[]", "required": false, "description": "Past clients their portfolio page lists (claimed, not verified). Also merged into claimed_brands and brands_worked.", "constraints": [] }, { "name": "data.turnaround_days", "type": "integer | null", "required": false, "description": "Stated delivery time in days; null when not stated.", "constraints": [] }, { "name": "data.sample_videos", "type": "string[]", "required": false, "description": "TikTok, Instagram or YouTube video URLs from their portfolio page, up to 6. Empty until the creator is unlocked.", "constraints": [] }, { "name": "data.portfolio_pages", "type": "object[]", "required": false, "description": "The link-in-bio, portfolio, media kit, rate card or website pages the rates were read from. Empty until the creator is unlocked.", "constraints": [] }, { "name": "data.portfolio_pages.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.portfolio_pages.kind", "type": "enum", "required": false, "enum": [ "link_in_bio", "portfolio", "media_kit", "rate_card", "own_site" ], "description": "", "constraints": [] }, { "name": "data.demand", "type": "enum", "required": false, "enum": [ "untapped", "low", "medium", "high" ], "description": "How many other brands were delivered this creator: untapped 0, low 1 to 2, medium 3 to 5, high 6 or more. Your own unlock is not counted.", "constraints": [] }, { "name": "data.fit_score", "type": "integer", "required": false, "description": "Score from public signals: UGC wording, portfolio, email kind, brand collabs, engagement, country, recency and bio length, plus a boost for verified UGC brand work, a 30%+ hit rate and a stated UGC video rate (capped at 100).", "constraints": [ "min 0", "max 100" ] }, { "name": "data.completeness", "type": "integer", "required": false, "description": "Share of profile fields present.", "constraints": [ "min 0", "max 100" ] }, { "name": "data.unlocked", "type": "boolean", "required": false, "description": "True when you can see the creator in full.", "constraints": [] }, { "name": "data.added_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "already_unlocked_ids", "type": "string[]", "required": false, "description": "Already delivered to you; not charged.", "constraints": [] }, { "name": "not_found_ids", "type": "string[]", "required": false, "description": "No longer in the database.", "constraints": [] }, { "name": "skipped_ids", "type": "string[]", "required": false, "description": "Found but could not be saved (for example no email on record); not charged.", "constraints": [] }, { "name": "access", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "access.object", "type": "enum", "required": false, "enum": [ "database_access" ], "description": "", "constraints": [] }, { "name": "access.plan", "type": "string", "required": false, "description": "The plan in effect, inherited from the team owner for team members.", "constraints": [] }, { "name": "access.can_unlock", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "access.leads_remaining", "type": "integer | null", "required": false, "description": "Leads left this month; null when the pool is unlimited.", "constraints": [] }, { "name": "access.monthly_lead_limit", "type": "integer | null", "required": false, "description": "Monthly lead pool; null when unlimited.", "constraints": [] } ], "example": { "object": "database_unlock", "charged_leads": 1, "data": [ { "object": "database_creator", "id": "4a30ae6c58106d121b34c29b174826b01bc28198ef159a71e16efe2a62f7bffa", "platform": "instagram", "handle": "anna.ugc", "email": "anna@gmail.com", "email_masked": "a••••@gmail.com", "unlocked": true } ], "already_unlocked_ids": [], "not_found_ids": [], "skipped_ids": [], "access": { "object": "database_access", "plan": "pro", "can_unlock": true, "leads_remaining": 499, "monthly_lead_limit": 500 } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "upgrade_required (with error.required_plan) when the plan cannot\nunlock creators, or lead_quota_exceeded when the monthly lead pool\ncannot cover the new unlocks. Nothing is charged.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] } ] }, { "name": "UGC Brands", "endpoints": [ { "id": "listUgcBrands", "method": "GET", "path": "/v1/ugc-brands", "group": "UGC Brands", "summary": "List UGC brands", "description": "Browses the UGC Brands database, the same dataset as the app's UGC\nBrands tab: brands that run UGC creator programs, with program facts\n(public pay per video, program hashtags, sources) and 30-day KPIs over\nthe creator accounts attributed to each program. The dataset is\ncurated ahead of time, so reads are instant and are not billed: they\nconsume no credits and no job-creating calls. Rate limit bucket\n`ugc_brands`, 240 requests per minute.\n\nDefault order is most 30-day views first. Every plan with access sees\nthe list; `summary.top_video` is null below Premium (API keys are\nUltra or Enterprise, so they always get it).\n\nKPIs count confirmed and likely accounts only. Image URLs\n(`logo_url`, `summary.top_video.thumbnail_url`) are served through the\napp's media cache (`/api/avatar`), never as expiring Instagram or\nTikTok CDN links; images hosted elsewhere pass through unchanged.\n\nTo research a brand that is not in this dataset, use\n`/v1/brand-researches` (a billed background job) instead.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page (prefixed ubc_).", "constraints": [ "max length 512" ] }, { "name": "q", "in": "query", "required": false, "type": "string", "description": "Case-insensitive substring of the brand name, domain or category.", "example": "study", "constraints": [ "min length 1", "max length 200" ] }, { "name": "category", "in": "query", "required": false, "type": "string", "description": "Comma-separated categories (1 to 20, case-insensitive exact match).", "example": "AI study tools", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "string", "description": "Comma-separated list of tiktok, instagram. Keeps brands with counted accounts on any of them.", "example": "tiktok", "constraints": [] }, { "name": "size", "in": "query", "required": false, "type": "string", "description": "Comma-separated program sizes by counted accounts: s (1 to 10), m (11 to 50), l (51 to 200), xl (201 and up).", "example": "l,xl", "constraints": [] }, { "name": "market", "in": "query", "required": false, "type": "string", "description": "Comma-separated ISO 3166-1 alpha-2 codes (1 to 20), matched against the brand's top three creator countries.", "example": "US,DE", "constraints": [] }, { "name": "pay_rate", "in": "query", "required": false, "type": "enum", "description": "public: a per-video rate is published. unknown: it is not.", "enum": [ "public", "unknown" ], "constraints": [] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "Descending for the numeric sorts, alphabetical for name. views_total is all-time views on every brand video held.", "default": "views_30d", "enum": [ "views_30d", "views_total", "accounts", "brand_videos_30d", "name" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of brands.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "ugc_brand" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.domain", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.logo_url", "type": "string | null", "required": false, "description": "Platform images go through the media cache; logos on other hosts pass through.", "constraints": [] }, { "name": "data.category", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.description", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.founded", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.official_handles", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "data.official_handles.tiktok", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.official_handles.instagram", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.program", "type": "object", "required": false, "description": "How the brand runs its creator program, from public sources.", "constraints": [] }, { "name": "data.program.model", "type": "string | null", "required": false, "description": "How the program works, in a sentence or two.", "constraints": [] }, { "name": "data.program.pay_per_video_usd", "type": "number | null", "required": false, "description": "Guaranteed base rate per video in USD, from the brand's program page or public job posts (see pay); null when not found. Drives est_payout and est_cpm.", "constraints": [] }, { "name": "data.program.bonus_note", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.program.cadence_note", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.program.ambassador_hashtags", "type": "string[]", "required": false, "description": "Program hashtags used to attribute accounts.", "constraints": [] }, { "name": "data.program.disclosure_tokens", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.program.markets_targeted", "type": "string[]", "required": false, "description": "ISO 3166-1 alpha-2 codes.", "constraints": [] }, { "name": "data.program.sources", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.program.pay", "type": "null | object", "required": false, "description": "Researched creator pay with its evidence; null when nothing brand-specific was found.", "constraints": [] }, { "name": "data.summary", "type": "object | null", "required": false, "description": "Null for a brand that has not been scanned yet.", "constraints": [] }, { "name": "data.data_as_of", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.last_scan", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.last_scan.candidates_checked", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.last_scan.accounts", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.last_scan.videos_read", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.last_scan.ran_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "ugc_brand", "id": "anara", "name": "Anara", "domain": "anara.com", "logo_url": "https://anara.com/logo.png", "category": "AI study tools", "description": "AI study workspace for students.", "founded": "2023", "official_handles": { "tiktok": "anara", "instagram": "anara.ai" }, "program": { "model": "Pays student creators per video, with view bonuses.", "pay_per_video_usd": 25, "bonus_note": "View bonuses on top of the base rate.", "cadence_note": null, "ambassador_hashtags": [ "#anaraambassador" ], "disclosure_tokens": [ "#ad" ], "markets_targeted": [ "US", "DE" ], "sources": [ { "label": "Program page", "url": "https://anara.com/creators" } ] }, "summary": { "accounts": 412, "accounts_by_confidence": { "confirmed": 300, "likely": 112, "possible": 40 }, "active_30d": 250, "brand_videos_30d": 3100, "views_30d": 41000000, "views_total": 318000000, "median_views_30d": 900, "est_payout_30d": 77500, "est_cpm_30d": 1.89 }, "data_as_of": "2026-10-05T12:00:00.000Z", "last_scan": { "candidates_checked": 1200, "accounts": 452, "videos_read": 15000, "ran_at": "2026-10-05T12:00:00.000Z" } } ], "has_more": true, "next_cursor": "ubc_eyJvIjoyNX0" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getUgcBrand", "method": "GET", "path": "/v1/ugc-brands/{id}", "group": "UGC Brands", "summary": "Retrieve a UGC brand", "description": "The brand page: everything in the list item plus `access` (your\nplan's tier), `overview` (the top 6 counted accounts by 30-day\nviews, and one `{posted_at, views}` point per counted brand video in\nthe last 31 days for charting) and `range`: the app's Overview tab\nfor a date window you pick, with the same KPIs, top accounts and a\nbucketed view series.\n\nPick the window with `window` (a rolling preset ending now) or\n`from`/`to` (a custom range), not both. With neither, `range` is the\nlast 30 days and equals the 30-day fields of `summary`; `window=all`\nequals `summary.views_total`.\n\nPlan gate (same as the app): the brand page needs Pro or higher.\nBelow that the call answers 402 `upgrade_required` with\n`required_plan: pro`, before any lookup.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Brand id from GET /v1/ugc-brands (case-insensitive).", "example": "anara", "constraints": [] }, { "name": "window", "in": "query", "required": false, "type": "enum", "description": "Rolling window ending now. all starts at the first brand video held.", "default": "30d", "enum": [ "7d", "30d", "90d", "365d", "all" ], "constraints": [] }, { "name": "from", "in": "query", "required": false, "type": "string", "description": "Custom range start: YYYY-MM-DD (UTC midnight) or an ISO 8601 date-time. Omit for all time up to `to`.", "example": "2026-09-01", "constraints": [] }, { "name": "to", "in": "query", "required": false, "type": "string", "description": "Custom range end: YYYY-MM-DD is inclusive (the whole UTC day counts); a date-time is exclusive. Defaults to now; capped at now.", "example": "2026-09-30", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The brand page.", "fields": [], "example": { "object": "ugc_brand", "id": "anara", "name": "Anara", "domain": "anara.com", "category": "AI study tools", "program": { "pay_per_video_usd": 25, "ambassador_hashtags": [ "#anaraambassador" ] }, "summary": { "accounts": 412, "views_30d": 41000000 }, "data_as_of": "2026-10-05T12:00:00.000Z", "access": { "plan": "ultra", "tier": "full", "overview_plan": "pro", "full_plan": "premium" }, "overview": { "top_accounts": [ { "id": "tiktok_studywithmaya", "platform": "tiktok", "handle": "studywithmaya", "profile_url": "https://www.tiktok.com/@studywithmaya", "display_name": "Maya", "avatar_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fp16-sign.tiktokcdn-us.com%2F...&h=studywithmaya", "followers": 1200, "videos_30d": 14, "views_30d": 3100000 } ], "recent_videos": [ { "posted_at": "2026-09-06T08:00:00.000Z", "views": 1200 } ] }, "range": { "from": "2026-09-01T00:00:00.000Z", "to": "2026-10-01T00:00:00.000Z", "preset": null, "days": 30, "accounts_active": 250, "new_accounts": 31, "brand_videos": 3100, "views": 41000000, "median_views": 900, "est_payout": 77500, "est_cpm": 1.89, "top_accounts": [ { "id": "tiktok_studywithmaya", "platform": "tiktok", "handle": "studywithmaya", "profile_url": "https://www.tiktok.com/@studywithmaya", "display_name": "Maya", "avatar_url": null, "followers": 1200, "videos": 14, "views": 3100000 } ], "granularity": "day", "series": [ { "start": "2026-09-01T00:00:00.000Z", "views": 1300000, "videos": 102 } ] } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace plan does not include this feature in the app either.\nerror.code is upgrade_required and error.required_plan names the\nlowest plan that unlocks it. Branch on error.code, not error.type.\nMessages never contain prices.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "listUgcBrandAccounts", "method": "GET", "path": "/v1/ugc-brands/{id}/accounts", "group": "UGC Brands", "summary": "List a brand's creator accounts", "description": "The accounts attributed to the brand's UGC program, with the evidence\nbehind each one (`confidence`, `signals`) and their output. The roster\nincludes `possible` accounts with `counted: false`; those are excluded\nfrom every KPI, video list and playbook, as in the app.\n\nEach account carries the creator's `email` when we hold one, with no\nlead charge. Pass `has_email=true` to page only through those.\n\nConfidence: `confirmed` means the bio says the account grows the brand\nor 2+ posts carry the program hashtag; `likely` means a program\nhashtag or caption template plus supporting evidence; `possible`\nmeans the brand is mentioned in context with no program marker.\n\nPlan gate: Premium or higher. Pro answers 402 `upgrade_required` with\n`required_plan: premium`; a workspace without a paid plan gets `required_plan: pro`. Unknown brand\nids answer 404 `ugc_brand_not_found`. Avatars come through the media\ncache.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Brand id from GET /v1/ugc-brands (case-insensitive).", "example": "anara", "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page (prefixed ubc_).", "constraints": [ "max length 512" ] }, { "name": "confidence", "in": "query", "required": false, "type": "string", "description": "Comma-separated list of confirmed, likely, possible.", "example": "confirmed,likely", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "string", "description": "Comma-separated list of tiktok, instagram.", "example": "tiktok", "constraints": [] }, { "name": "dedicated", "in": "query", "required": false, "type": "enum", "description": "true: only accounts that exist to post for the brand. false: only personal accounts.", "enum": [ "true", "false" ], "constraints": [] }, { "name": "has_email", "in": "query", "required": false, "type": "enum", "description": "true: only accounts with an email. false: only accounts without one.", "enum": [ "true", "false" ], "constraints": [] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "Always descending.", "default": "views_30d", "enum": [ "views_30d", "videos_30d", "followers", "median_views", "best_video_views", "score", "first_brand_video_at", "last_brand_video_at" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of attributed accounts.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "ugc_brand_account" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Platform and handle, e.g. tiktok_studywithmaya.", "constraints": [] }, { "name": "data.brand_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram" ], "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.avatar_url", "type": "string | null", "required": false, "description": "Served through the media cache.", "constraints": [] }, { "name": "data.bio", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.bio_link", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "The creator's contact email, or null when we hold none. Never an address on the brand's own domain.", "constraints": [] }, { "name": "data.email_kind", "type": "enum", "required": false, "enum": [ "personal", "creator_domain", "agency", "unknown", null ], "description": "What kind of inbox it is. Null when there is no email.", "constraints": [] }, { "name": "data.email_source", "type": "string | null", "required": false, "description": "Where the email was found, e.g. bio or portfolio. Null when there is no email.", "constraints": [] }, { "name": "data.followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.following", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.total_videos", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.total_likes", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.verified", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.account_created_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.region", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.language", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.country", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.country_basis", "type": "string | null", "required": false, "description": "What the country was inferred from.", "constraints": [] }, { "name": "data.confidence", "type": "enum", "required": false, "enum": [ "confirmed", "likely", "possible" ], "description": "", "constraints": [] }, { "name": "data.counted", "type": "boolean", "required": false, "description": "false for possible accounts, which are excluded from KPIs, videos and the playbook.", "constraints": [] }, { "name": "data.dedicated", "type": "boolean", "required": false, "description": "The account exists to post for the brand.", "constraints": [] }, { "name": "data.score", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "data.signals", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.signals.type", "type": "enum", "required": false, "enum": [ "bio_program", "bio_mention", "ambassador_hashtag", "caption_template", "caption_mention", "disclosure", "ad_flag", "seed", "handle_program", "handle_pattern" ], "description": "", "constraints": [] }, { "name": "data.signals.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.signals.evidence", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.signals.weight", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "data.stats", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.brand_videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.videos_30d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.views_30d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.median_views_30d", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.median_views", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.engagement_rate_30d", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.posts_per_week", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.best_video", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.first_brand_video_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.last_brand_video_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.trend", "type": "number[]", "required": false, "description": "", "constraints": [] }, { "name": "data.refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "ugc_brand_account", "id": "tiktok_studywithmaya", "brand_id": "anara", "platform": "tiktok", "handle": "studywithmaya", "profile_url": "https://www.tiktok.com/@studywithmaya", "display_name": "Maya", "avatar_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fp16-sign.tiktokcdn-us.com%2F...&h=studywithmaya", "bio": "growing @anara", "followers": 1200, "country": "US", "confidence": "confirmed", "counted": true, "dedicated": true, "score": 11, "signals": [ { "type": "bio_program", "label": "Bio says the account grows the brand", "evidence": "growing @anara", "weight": 5 } ], "stats": { "brand_videos": 40, "videos_30d": 14, "views_30d": 3100000, "median_views_30d": 2100, "median_views": 1800, "engagement_rate_30d": 0.07, "posts_per_week": 3.3, "best_video": { "id": "7412000000000000000", "url": "https://www.tiktok.com/@studywithmaya/video/7412000000000000000", "views": 2400000 }, "first_brand_video_at": "2026-05-03T00:00:00.000Z", "last_brand_video_at": "2026-10-04T00:00:00.000Z", "trend": [ 1200, 800, 2400000 ] }, "refreshed_at": "2026-10-05T12:00:00.000Z" } ], "has_more": false, "next_cursor": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace plan does not include this feature in the app either.\nerror.code is upgrade_required and error.required_plan names the\nlowest plan that unlocks it. Branch on error.code, not error.type.\nMessages never contain prices.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getUgcBrandAccount", "method": "GET", "path": "/v1/ugc-brands/{id}/accounts/{account_id}", "group": "UGC Brands", "summary": "Retrieve a brand account", "description": "One attributed account (the app's account drawer): the roster fields\nplus `videos`, every video held for the account, brand and non-brand.\nEach video carries `is_brand`, `brand_evidence` and\n`outlier_multiple` (views over the account's median brand video; null\nfor non-brand videos). Takes no query parameters.\n\nPlan gate: Premium or higher (402 `upgrade_required`). Unknown ids\nanswer 404 `ugc_brand_not_found` or `ugc_brand_account_not_found`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Brand id from GET /v1/ugc-brands (case-insensitive).", "example": "anara", "constraints": [] }, { "name": "account_id", "in": "path", "required": true, "type": "string", "description": "Account id from the roster, the platform and handle joined by an underscore.", "example": "tiktok_studywithmaya", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The account with its videos.", "fields": [] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace plan does not include this feature in the app either.\nerror.code is upgrade_required and error.required_plan names the\nlowest plan that unlocks it. Branch on error.code, not error.type.\nMessages never contain prices.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "listUgcBrandVideos", "method": "GET", "path": "/v1/ugc-brands/{id}/videos", "group": "UGC Brands", "summary": "List a brand's videos", "description": "Brand videos posted by counted (confirmed and likely) accounts, the\napp's Videos tab. `outliers` sorts by `outlier_multiple`, a video's\nviews divided by its account's median brand video. Thumbnails and\navatars come through the media cache.\n\nPlan gate: Premium or higher (402 `upgrade_required`).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Brand id from GET /v1/ugc-brands (case-insensitive).", "example": "anara", "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page (prefixed ubc_).", "constraints": [ "max length 512" ] }, { "name": "window", "in": "query", "required": false, "type": "enum", "description": "30d: brand videos from the last 30 days. all: every brand video held.", "default": "30d", "enum": [ "30d", "all" ], "constraints": [] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "views: most viewed. outliers: biggest multiple of the account median. recent: newest first.", "default": "views", "enum": [ "views", "outliers", "recent" ], "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "string", "description": "Comma-separated list of tiktok, instagram.", "example": "tiktok", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of brand videos.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "ugc_brand_video" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.caption", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.thumbnail_url", "type": "string | null", "required": false, "description": "Served through the media cache.", "constraints": [] }, { "name": "data.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.saves", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.is_slideshow", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.is_ad", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.language", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.music", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.is_brand", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.brand_evidence", "type": "string | null", "required": false, "description": "Why the video counts as a brand video.", "constraints": [] }, { "name": "data.brand_id", "type": "string", "required": false, "description": "Not present on videos nested in an account.", "constraints": [] }, { "name": "data.account", "type": "object", "required": false, "description": "Not present on videos nested in an account.", "constraints": [] }, { "name": "data.account.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.account.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram" ], "description": "", "constraints": [] }, { "name": "data.account.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.account.profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.account.display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.account.avatar_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.account.followers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.account.confidence", "type": "enum", "required": false, "enum": [ "confirmed", "likely", "possible" ], "description": "", "constraints": [] }, { "name": "data.outlier_multiple", "type": "number | null", "required": false, "description": "Views over the account's median brand video; null for non-brand videos.", "constraints": [] }, { "name": "data.history", "type": "object[]", "required": false, "description": "Metric snapshots over time.", "constraints": [] }, { "name": "data.history.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.history.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.saves", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "ugc_brand_video", "id": "7412000000000000000", "url": "https://www.tiktok.com/@studywithmaya/video/7412000000000000000", "caption": "POV: you found the study app #anaraambassador", "thumbnail_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fp16-sign.tiktokcdn.com%2F...&k=t&post=https%3A%2F%2Fwww.tiktok.com%2F%40studywithmaya%2Fvideo%2F7412000000000000000", "posted_at": "2026-10-01T15:00:00.000Z", "duration_s": 18, "views": 2400000, "likes": 210000, "comments": 900, "shares": 4000, "saves": 12000, "is_slideshow": false, "is_ad": false, "language": "en", "hashtags": [ "#anaraambassador" ], "music": null, "is_brand": true, "brand_evidence": "Program hashtag #anaraambassador", "brand_id": "anara", "account": { "id": "tiktok_studywithmaya", "platform": "tiktok", "handle": "studywithmaya", "profile_url": "https://www.tiktok.com/@studywithmaya", "display_name": "Maya", "followers": 1200, "confidence": "confirmed" }, "outlier_multiple": 1333.3, "history": [ { "at": "2026-10-02T00:00:00.000Z", "views": 900000, "likes": 80000, "comments": 300, "shares": 1000, "saves": 5000 } ] } ], "has_more": true, "next_cursor": "ubc_eyJvIjoyNX0" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace plan does not include this feature in the app either.\nerror.code is upgrade_required and error.required_plan names the\nlowest plan that unlocks it. Branch on error.code, not error.type.\nMessages never contain prices.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getUgcBrandPlaybook", "method": "GET", "path": "/v1/ugc-brands/{id}/playbook", "group": "UGC Brands", "summary": "Retrieve a brand's playbook", "description": "What the brand's UGC creators do that works, computed over counted\naccounts' brand videos (the app's Playbook tab): the top 8 reused\ncaption openers (first 6 words, reused 2+ times), the top 12 hashtags,\nvideo vs slideshow, duration buckets with the best-performing length,\nthe virality spread (multiples of each account's median brand video),\nengagement totals and account naming patterns. The app's posting-time\nheatmap is not included; derive it from `posted_at` in\nGET /v1/ugc-brands/{id}/videos.\n\nPlan gate: Premium or higher (402 `upgrade_required`).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Brand id from GET /v1/ugc-brands (case-insensitive).", "example": "anara", "constraints": [] }, { "name": "window", "in": "query", "required": false, "type": "enum", "description": "30d: brand videos from the last 30 days. all: every brand video held.", "default": "30d", "enum": [ "30d", "all" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The playbook.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "ugc_brand_playbook" ], "description": "", "constraints": [] }, { "name": "brand_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window", "type": "enum", "required": false, "enum": [ "30d", "all" ], "description": "", "constraints": [] }, { "name": "videos_analyzed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "caption_openers", "type": "object[]", "required": false, "description": "Top 8 groups of the first 6 caption words reused 2+ times, by accounts then videos.", "constraints": [] }, { "name": "caption_openers.opener", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "caption_openers.example", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "caption_openers.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "caption_openers.accounts", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "caption_openers.median_views", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "hashtags", "type": "object[]", "required": false, "description": "Top 12 hashtags.", "constraints": [] }, { "name": "hashtags.tag", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "hashtags.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "hashtags.median_views", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "hashtags.share", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "formats", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "formats.format", "type": "enum", "required": false, "enum": [ "video", "slideshow" ], "description": "", "constraints": [] }, { "name": "formats.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "formats.median_views", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "duration", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "duration.buckets", "type": "object[]", "required": false, "description": "0-15s, 15-30s, 30-45s, 45-60s, 1-1.5m, 1.5-3m, 3m+.", "constraints": [] }, { "name": "duration.buckets.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "duration.buckets.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "duration.buckets.avg_views", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "duration.buckets.median_views", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "duration.buckets.best", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "duration.optimal_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration.median_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "virality", "type": "object[]", "required": false, "description": "Share of videos by multiple of the account median: below 1x, 1-5x, 5-10x, 10-25x, 25-50x, 50-100x, 100x+.", "constraints": [] }, { "name": "virality.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "virality.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "virality.min_multiple", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "virality.max_multiple", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "virality.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "virality.share", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "engagement", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "engagement.likes", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "engagement.comments", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "engagement.shares", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "engagement.saves", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "engagement.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "account_naming", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "account_naming.patterns", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "account_naming.patterns.pattern", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "account_naming.patterns.accounts", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "account_naming.patterns.examples", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "account_naming.personal_style_accounts", "type": "integer", "required": false, "description": "", "constraints": [] } ], "example": { "object": "ugc_brand_playbook", "brand_id": "anara", "window": "30d", "videos_analyzed": 3100, "caption_openers": [ { "opener": "pov you found the study app", "example": "POV: you found the study app ...", "videos": 120, "accounts": 40, "median_views": 1500 } ], "hashtags": [ { "tag": "#anaraambassador", "videos": 2900, "median_views": 900, "share": 0.93 } ], "formats": [ { "format": "video", "videos": 1800, "median_views": 1100 }, { "format": "slideshow", "videos": 1300, "median_views": 700 } ], "duration": { "buckets": [ { "label": "0-15s", "videos": 900, "avg_views": 8000, "median_views": 700, "best": false } ], "optimal_duration_s": 21.4, "median_duration_s": 18 }, "virality": [ { "label": "10-25x", "name": "Outlier", "min_multiple": 10, "max_multiple": 25, "videos": 120, "share": 0.04 } ], "engagement": { "likes": 1200000, "comments": 30000, "shares": 45000, "saves": 90000, "engagement_rate": 0.06 }, "account_naming": { "patterns": [ { "pattern": "*pages", "accounts": 30, "examples": [ "mayapages" ] } ], "personal_style_accounts": 300 } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "402", "description": "The workspace plan does not include this feature in the app either.\nerror.code is upgrade_required and error.required_plan names the\nlowest plan that unlocks it. Branch on error.code, not error.type.\nMessages never contain prices.\n" }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] } ] }, { "name": "Creator Tracking", "endpoints": [ { "id": "getTrackingSummary", "method": "GET", "path": "/v1/tracking", "group": "Creator Tracking", "summary": "Get the tracking summary", "description": "The Creator Tracking tab at a glance: how many accounts are tracked,\nthe plan's tracking cap (`limit`: Pro 25, Premium 100, Ultra\nand Enterprise 300), how many are still loading or errored, the date\nrange presets every view accepts, and the refresh policy.\n\nTracking is not billed per action: no endpoint under `/v1/tracking`\nconsumes credits, leads or job-creating calls. Data refreshes only when\nsomeone looks or asks for it, never on a schedule. Like opening the tab\nin the app, this call (and the accounts, videos, overview and payouts\nreads) refreshes accounts older than 12 hours in the background.\n\nTracked accounts belong to a person, as in the app. An API key acts as\nthe team member who created it (the workspace owner for keys created\nbefore member attribution). All tracking\nendpoints share a rate limit of 120 requests per minute per key and\nanswer with `Cache-Control: private, no-store`.\n", "deprecated": false, "comingSoon": false, "params": [], "body": null, "response": { "code": "200", "description": "The tracking summary.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_workspace" ], "description": "", "constraints": [] }, { "name": "limit", "type": "integer", "required": false, "description": "Accounts the plan can track: Pro 25, Premium 100, Ultra and Enterprise 300.", "constraints": [] }, { "name": "tracked", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "remaining", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "pending", "type": "integer", "required": false, "description": "Accounts whose first scrape is still running.", "constraints": [] }, { "name": "refreshing", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "errored", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "collections", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "ranges", "type": "object[]", "required": false, "description": "Range presets accepted by the range parameter.", "constraints": [] }, { "name": "ranges.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "ranges.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "refresh_policy", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "refresh_policy.auto_refresh_after_hours", "type": "number", "required": false, "description": "Reads refresh accounts older than this in the background.", "constraints": [] }, { "name": "refresh_policy.min_manual_refresh_interval_minutes", "type": "number", "required": false, "description": "A manual refresh within this interval returns stored data.", "constraints": [] } ], "example": { "object": "tracking_workspace", "limit": 300, "tracked": 42, "remaining": 258, "pending": 1, "refreshing": 3, "errored": 0, "collections": 2, "ranges": [ { "key": "today", "label": "Today" }, { "key": "7d", "label": "Last 7 days" } ], "refresh_policy": { "auto_refresh_after_hours": 12, "min_manual_refresh_interval_minutes": 10 } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "listTrackedAccounts", "method": "GET", "path": "/v1/tracking/accounts", "group": "Creator Tracking", "summary": "List tracked accounts", "description": "The Accounts table: every tracked Instagram and TikTok account with\nits stats for the selected `range`. `avatar_url` goes through the\napp's media proxy, so it does not expire like raw platform links.\n`spend`, `cpm`, `cpv` and `cpe` are null for accounts without a fee;\n`saves` is null where the platform hides bookmarks (Instagram). A\ncursor is only valid for the same filters (400 `invalid_cursor`\notherwise). Triggers the background refresh-on-view.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "range", "in": "query", "required": false, "type": "enum", "description": "Date range preset, same as the app's picker. Every range except all also has an equal-length previous period for deltas.", "default": "7d", "enum": [ "today", "yesterday", "7d", "30d", "last_month", "mtd", "ytd", "last_year", "all" ], "constraints": [] }, { "name": "timezone", "in": "query", "required": false, "type": "string", "description": "IANA time zone for day, week (Monday to Sunday) and month boundaries, e.g. America/New_York.", "default": "UTC", "constraints": [ "max length 64" ] }, { "name": "collection_id", "in": "query", "required": false, "type": "string", "description": "Only accounts in this collection, and only posts matching its terms and date window. 404 collection_not_found if unknown.", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "account_ids", "in": "query", "required": false, "type": "string", "description": "Comma-separated tracked account ids (1 to 300), e.g. tiktok_mia,instagram_bea.", "constraints": [] }, { "name": "q", "in": "query", "required": false, "type": "string", "description": "Case-insensitive match on handle or display name.", "constraints": [ "min length 1", "max length 200" ] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "Sort key. Accounts without a value sort last.", "default": "added_at", "enum": [ "added_at", "views", "views_gained", "followers", "engagement_rate", "videos", "spend", "cpm" ], "constraints": [] }, { "name": "order", "in": "query", "required": false, "type": "enum", "description": "", "default": "desc", "enum": [ "asc", "desc" ], "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of tracked accounts.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "tracking_account" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "platform_handle, e.g. tiktok_mia.", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.avatar_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "data.profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.source", "type": "enum", "required": false, "enum": [ "crm", "external" ], "description": "", "constraints": [] }, { "name": "data.collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.fee", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.fee_basis", "type": "enum", "required": false, "enum": [ "flat", "per_video", "cpm" ], "description": "", "constraints": [] }, { "name": "data.payout_status", "type": "enum", "required": false, "enum": [ "none", "pending", "approved", "paid", "assumed_paid" ], "description": "", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "pending", "ready", "error", "private" ], "description": "pending while the first scrape runs.", "constraints": [] }, { "name": "data.error", "type": "string | null", "required": false, "description": "User-facing message when status is error.", "constraints": [] }, { "name": "data.refreshing", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.video_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.added_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats", "type": "object", "required": false, "description": "Stats for the selected range. Ratios are fractions (0.052 = 5.2%); money is in workspace currency units.", "constraints": [] }, { "name": "data.stats.range", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.saves", "type": "integer | null", "required": false, "description": "Null where the platform hides bookmarks.", "constraints": [] }, { "name": "data.stats.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.highest_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.high_viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.avg_views_vs_followers", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.outliers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.posts_per_week", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.posting_activity_7d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.first_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.last_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.health_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.spend", "type": "number | null", "required": false, "description": "Null without a fee.", "constraints": [] }, { "name": "data.stats.cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.cpv", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.cpe", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.stats.weekly_quota", "type": "object | null", "required": false, "description": "Posting target progress for this week, from the account's own collection posts_per_week. Null without one.", "constraints": [] }, { "name": "data.stats.trend", "type": "number[]", "required": false, "description": "Small series for a sparkline.", "constraints": [] }, { "name": "data.window", "type": "object", "required": false, "description": "The resolved date window.", "constraints": [] }, { "name": "data.window.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.window.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.window.timezone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.window.start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.window.end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.window.previous_start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.window.previous_end", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.snapshots", "type": "object[]", "required": false, "description": "Account-level history, up to 120 readings.", "constraints": [] }, { "name": "data.snapshots.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.snapshots.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.snapshots.views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.daily_breakdown", "type": "object", "required": false, "description": "The last 14 days, newest first, plus averages.", "constraints": [] }, { "name": "data.daily_breakdown.days", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.daily_breakdown.average", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement_breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement_breakdown.id", "type": "enum", "required": false, "enum": [ "likes", "comments", "shares", "saves" ], "description": "", "constraints": [] }, { "name": "data.engagement_breakdown.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement_breakdown.value", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.duration_analysis", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "data.duration_analysis.buckets", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.duration_analysis.optimal_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "object": "tracking_account", "id": "tiktok_mia", "platform": "tiktok", "handle": "mia", "display_name": "Mia", "avatar_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fp16-sign.tiktokcdn.com%2Fa.jpg&h=mia", "profile_url": "https://www.tiktok.com/@mia", "followers": 10000, "source": "crm", "collection_id": "cmp_ab12cd34ef56", "fee": 200, "fee_basis": "per_video", "payout_status": "approved", "status": "ready", "error": null, "refreshing": false, "video_count": 24, "added_at": "2026-08-28T15:00:00.000Z", "refreshed_at": "2026-10-07T14:00:00.000Z", "stats": { "range": "7d", "videos": 2, "views": 51000, "views_gained": 30500, "engagement_rate": 0.1002, "median_views": 25500, "outliers": 1, "health_score": 6.8, "spend": 400, "cpm": 7.84, "weekly_quota": { "posted": 1, "expected": 3, "ratio": 0.3333 } } } ] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "trackAccounts", "method": "POST", "path": "/v1/tracking/accounts", "group": "Creator Tracking", "summary": "Track accounts", "description": "The app's \"Add creators\": start tracking up to 100 accounts per call,\nfrom the CRM or anywhere else. Each entry is a handle (`@mia`, `mia`,\n`tt:mia`), a profile link, or an object with `handle` and optional\ndetails. New accounts come back with `status: pending` and load in the\nbackground; poll GET /v1/tracking/accounts until they are `ready`.\n\nAdds past the plan's tracking cap are not an error: they come back in\n`skipped` with `code: plan_limit`, next to `already_tracked` and\n`invalid_handle`. Send an `Idempotency-Key` to make retries safe: the\nsame key and body replays the first result with\n`Idempotency-Replayed: true`; a different body answers 409.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "accounts", "type": "string | object[]", "required": true, "example": [ "@mia", "https://www.instagram.com/bea.ugc" ], "description": "Handles (@mia, mia, tt:mia), profile links, or objects.", "constraints": [ "min 1 items", "max 100 items" ] }, { "name": "source", "type": "enum", "required": false, "default": "external", "enum": [ "crm", "external" ], "example": "crm", "description": "Label only: crm when the creators come from the CRM.", "constraints": [] }, { "name": "collection_id", "type": "string | null", "required": false, "example": "cmp_ab12cd34ef56", "description": "Put the new accounts in this collection (404 collection_not_found if unknown).", "constraints": [] }, { "name": "default_platform", "type": "enum", "required": false, "default": "instagram", "enum": [ "instagram", "tiktok" ], "example": "tiktok", "description": "Platform for bare handles.", "constraints": [] } ], "example": { "accounts": [ "@mia", "https://www.instagram.com/bea.ugc", { "handle": "zed", "platform": "tiktok" } ], "source": "crm", "collection_id": "cmp_ab12cd34ef56", "default_platform": "tiktok" } }, "response": { "code": "200", "description": "What was added and what was skipped.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_account_batch" ], "description": "", "constraints": [] }, { "name": "added", "type": "object[]", "required": false, "description": "New accounts, without stats, status pending.", "constraints": [] }, { "name": "added.object", "type": "enum", "required": false, "enum": [ "tracking_account" ], "description": "", "constraints": [] }, { "name": "added.id", "type": "string", "required": false, "description": "platform_handle, e.g. tiktok_mia.", "constraints": [] }, { "name": "added.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "added.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.avatar_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "added.profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "added.source", "type": "enum", "required": false, "enum": [ "crm", "external" ], "description": "", "constraints": [] }, { "name": "added.collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.fee", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.fee_basis", "type": "enum", "required": false, "enum": [ "flat", "per_video", "cpm" ], "description": "", "constraints": [] }, { "name": "added.payout_status", "type": "enum", "required": false, "enum": [ "none", "pending", "approved", "paid", "assumed_paid" ], "description": "", "constraints": [] }, { "name": "added.status", "type": "enum", "required": false, "enum": [ "pending", "ready", "error", "private" ], "description": "pending while the first scrape runs.", "constraints": [] }, { "name": "added.error", "type": "string | null", "required": false, "description": "User-facing message when status is error.", "constraints": [] }, { "name": "added.refreshing", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "added.video_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.added_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats", "type": "object", "required": false, "description": "Stats for the selected range. Ratios are fractions (0.052 = 5.2%); money is in workspace currency units.", "constraints": [] }, { "name": "added.stats.range", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.saves", "type": "integer | null", "required": false, "description": "Null where the platform hides bookmarks.", "constraints": [] }, { "name": "added.stats.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.highest_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.high_viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.avg_views_vs_followers", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.outliers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.posts_per_week", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.posting_activity_7d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.first_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.last_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.health_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.spend", "type": "number | null", "required": false, "description": "Null without a fee.", "constraints": [] }, { "name": "added.stats.cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.cpv", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.cpe", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "added.stats.weekly_quota", "type": "object | null", "required": false, "description": "Posting target progress for this week, from the account's own collection posts_per_week. Null without one.", "constraints": [] }, { "name": "added.stats.trend", "type": "number[]", "required": false, "description": "Small series for a sparkline.", "constraints": [] }, { "name": "added.window", "type": "object", "required": false, "description": "The resolved date window.", "constraints": [] }, { "name": "added.window.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.window.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.window.timezone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.window.start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.window.end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.window.previous_start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.window.previous_end", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "added.snapshots", "type": "object[]", "required": false, "description": "Account-level history, up to 120 readings.", "constraints": [] }, { "name": "added.snapshots.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.snapshots.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "added.snapshots.views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "added.daily_breakdown", "type": "object", "required": false, "description": "The last 14 days, newest first, plus averages.", "constraints": [] }, { "name": "added.daily_breakdown.days", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "added.daily_breakdown.average", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "added.engagement_breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "added.engagement_breakdown.id", "type": "enum", "required": false, "enum": [ "likes", "comments", "shares", "saves" ], "description": "", "constraints": [] }, { "name": "added.engagement_breakdown.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "added.engagement_breakdown.value", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added.duration_analysis", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "added.duration_analysis.buckets", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "added.duration_analysis.optimal_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "skipped", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "skipped.input", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "skipped.code", "type": "enum", "required": false, "enum": [ "already_tracked", "invalid_handle", "plan_limit" ], "description": "", "constraints": [] }, { "name": "skipped.reason", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "limit", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "remaining", "type": "integer", "required": false, "description": "", "constraints": [] } ], "example": { "object": "tracking_account_batch", "added": [ { "object": "tracking_account", "id": "tiktok_mia", "platform": "tiktok", "handle": "mia", "status": "pending", "video_count": 0 } ], "skipped": [ { "input": "@bea", "code": "already_tracked", "reason": "Already tracked" }, { "input": "@zed", "code": "plan_limit", "reason": "Your plan tracks up to 300 creators" } ], "limit": 300, "remaining": 257 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getTrackedAccount", "method": "GET", "path": "/v1/tracking/accounts/{id}", "group": "Creator Tracking", "summary": "Retrieve a tracked account", "description": "The account page: the account with `stats` for the range plus the\nresolved `window`, account-level `snapshots` (followers and total\nviews, up to 120), the last 14 days in `daily_breakdown`, the\n`engagement_breakdown` and the `duration_analysis`. For the account's\nchart call GET /v1/tracking/overview with `account_ids` set to this id.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Tracked account id: platform, underscore, lowercase handle (e.g. tiktok_mia).", "constraints": [] }, { "name": "range", "in": "query", "required": false, "type": "enum", "description": "Date range preset, same as the app's picker. Every range except all also has an equal-length previous period for deltas.", "default": "7d", "enum": [ "today", "yesterday", "7d", "30d", "last_month", "mtd", "ytd", "last_year", "all" ], "constraints": [] }, { "name": "timezone", "in": "query", "required": false, "type": "string", "description": "IANA time zone for day, week (Monday to Sunday) and month boundaries, e.g. America/New_York.", "default": "UTC", "constraints": [ "max length 64" ] }, { "name": "collection_id", "in": "query", "required": false, "type": "string", "description": "Only accounts in this collection, and only posts matching its terms and date window. 404 collection_not_found if unknown.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The account with its detail modules.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_account" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "platform_handle, e.g. tiktok_mia.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "avatar_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "source", "type": "enum", "required": false, "enum": [ "crm", "external" ], "description": "", "constraints": [] }, { "name": "collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "fee", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "fee_basis", "type": "enum", "required": false, "enum": [ "flat", "per_video", "cpm" ], "description": "", "constraints": [] }, { "name": "payout_status", "type": "enum", "required": false, "enum": [ "none", "pending", "approved", "paid", "assumed_paid" ], "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "pending", "ready", "error", "private" ], "description": "pending while the first scrape runs.", "constraints": [] }, { "name": "error", "type": "string | null", "required": false, "description": "User-facing message when status is error.", "constraints": [] }, { "name": "refreshing", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "video_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "stats", "type": "object", "required": false, "description": "Stats for the selected range. Ratios are fractions (0.052 = 5.2%); money is in workspace currency units.", "constraints": [] }, { "name": "stats.range", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "stats.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.saves", "type": "integer | null", "required": false, "description": "Null where the platform hides bookmarks.", "constraints": [] }, { "name": "stats.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.highest_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.high_viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.avg_views_vs_followers", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.outliers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.posts_per_week", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.posting_activity_7d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.first_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.last_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.health_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.spend", "type": "number | null", "required": false, "description": "Null without a fee.", "constraints": [] }, { "name": "stats.cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.cpv", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.cpe", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.weekly_quota", "type": "object | null", "required": false, "description": "Posting target progress for this week, from the account's own collection posts_per_week. Null without one.", "constraints": [] }, { "name": "stats.weekly_quota.posted", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.weekly_quota.expected", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.weekly_quota.ratio", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stats.trend", "type": "number[]", "required": false, "description": "Small series for a sparkline.", "constraints": [] }, { "name": "window", "type": "object", "required": false, "description": "The resolved date window.", "constraints": [] }, { "name": "window.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.timezone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_end", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "snapshots", "type": "object[]", "required": false, "description": "Account-level history, up to 120 readings.", "constraints": [] }, { "name": "snapshots.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "snapshots.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "snapshots.views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown", "type": "object", "required": false, "description": "The last 14 days, newest first, plus averages.", "constraints": [] }, { "name": "daily_breakdown.days", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.date", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.total_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.likes_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.comments_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.uploads", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.partial", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.average", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown.id", "type": "enum", "required": false, "enum": [ "likes", "comments", "shares", "saves" ], "description": "", "constraints": [] }, { "name": "engagement_breakdown.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown.value", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.best", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.optimal_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "updateTrackedAccount", "method": "PATCH", "path": "/v1/tracking/accounts/{id}", "group": "Creator Tracking", "summary": "Update a tracked account", "description": "Moves the account into or out of a collection and sets its payout\nterms. Send at least one field (400 `empty_update` otherwise). Returns\nthe account without `stats`. Accepts an `Idempotency-Key`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Tracked account id: platform, underscore, lowercase handle (e.g. tiktok_mia).", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "collection_id", "type": "string | null", "required": false, "example": "cmp_ab12cd34ef56", "description": "Collection to move into; null removes it from its collection.", "constraints": [] }, { "name": "fee", "type": "number | null", "required": false, "example": 200, "description": "What the account is paid; null clears it.", "constraints": [ "min 0", "max 10000000" ] }, { "name": "fee_basis", "type": "enum", "required": false, "enum": [ "flat", "per_video", "cpm" ], "example": "per_video", "description": "flat: one fee for the collection. per_video: fee times videos. cpm: fee per 1,000 views gained.", "constraints": [] }, { "name": "payout_status", "type": "enum", "required": false, "enum": [ "none", "pending", "approved", "paid", "assumed_paid" ], "example": "approved", "description": "", "constraints": [] } ], "example": { "collection_id": "cmp_ab12cd34ef56", "fee": 200, "fee_basis": "per_video", "payout_status": "approved" } }, "response": { "code": "200", "description": "The updated account.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_account" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "platform_handle, e.g. tiktok_mia.", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "display_name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "avatar_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "profile_url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "source", "type": "enum", "required": false, "enum": [ "crm", "external" ], "description": "", "constraints": [] }, { "name": "collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "fee", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "fee_basis", "type": "enum", "required": false, "enum": [ "flat", "per_video", "cpm" ], "description": "", "constraints": [] }, { "name": "payout_status", "type": "enum", "required": false, "enum": [ "none", "pending", "approved", "paid", "assumed_paid" ], "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "pending", "ready", "error", "private" ], "description": "pending while the first scrape runs.", "constraints": [] }, { "name": "error", "type": "string | null", "required": false, "description": "User-facing message when status is error.", "constraints": [] }, { "name": "refreshing", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "video_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "added_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "refreshed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "stats", "type": "object", "required": false, "description": "Stats for the selected range. Ratios are fractions (0.052 = 5.2%); money is in workspace currency units.", "constraints": [] }, { "name": "stats.range", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "stats.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.saves", "type": "integer | null", "required": false, "description": "Null where the platform hides bookmarks.", "constraints": [] }, { "name": "stats.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.highest_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.high_viral_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.avg_views_vs_followers", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.outliers", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.posts_per_week", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.posting_activity_7d", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.first_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.last_post_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.health_score", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.spend", "type": "number | null", "required": false, "description": "Null without a fee.", "constraints": [] }, { "name": "stats.cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.cpv", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.cpe", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "stats.weekly_quota", "type": "object | null", "required": false, "description": "Posting target progress for this week, from the account's own collection posts_per_week. Null without one.", "constraints": [] }, { "name": "stats.weekly_quota.posted", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.weekly_quota.expected", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "stats.weekly_quota.ratio", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "stats.trend", "type": "number[]", "required": false, "description": "Small series for a sparkline.", "constraints": [] }, { "name": "window", "type": "object", "required": false, "description": "The resolved date window.", "constraints": [] }, { "name": "window.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.timezone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_end", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "snapshots", "type": "object[]", "required": false, "description": "Account-level history, up to 120 readings.", "constraints": [] }, { "name": "snapshots.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "snapshots.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "snapshots.views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown", "type": "object", "required": false, "description": "The last 14 days, newest first, plus averages.", "constraints": [] }, { "name": "daily_breakdown.days", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.date", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.total_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.likes_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.comments_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.uploads", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.days.partial", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "daily_breakdown.average", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown.id", "type": "enum", "required": false, "enum": [ "likes", "comments", "shares", "saves" ], "description": "", "constraints": [] }, { "name": "engagement_breakdown.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown.value", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.best", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.optimal_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "untrackAccount", "method": "DELETE", "path": "/v1/tracking/accounts/{id}", "group": "Creator Tracking", "summary": "Stop tracking an account", "description": "Stops tracking the account and removes its stored videos and snapshots. Accepts an `Idempotency-Key`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Tracked account id: platform, underscore, lowercase handle (e.g. tiktok_mia).", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "204", "description": "Removed.", "fields": [], "example": null }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "refreshTrackedAccount", "method": "POST", "path": "/v1/tracking/accounts/{id}/refresh", "group": "Creator Tracking", "summary": "Refresh a tracked account", "description": "The app's per-account Refresh button. Scrapes the account's latest\nvideos now and answers when done. If the account was refreshed in the\nlast 10 minutes it returns the stored data with `throttled: true`\ninstead. Concurrent refreshes of one account share a single scrape.\nNo request body. An `Idempotency-Key` is validated but not needed:\nthe throttle already makes repeats harmless.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Tracked account id: platform, underscore, lowercase handle (e.g. tiktok_mia).", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The refreshed account.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_refresh" ], "description": "", "constraints": [] }, { "name": "account", "type": "object | null", "required": false, "description": "The account (single refresh) or null (refresh all).", "constraints": [] }, { "name": "throttled", "type": "boolean", "required": false, "description": "True when stored data was returned or nothing was queued because of the 10 minute floor.", "constraints": [] }, { "name": "queued", "type": "integer", "required": false, "description": "Accounts queued by a refresh all; 0 for a single refresh.", "constraints": [] } ], "example": { "object": "tracking_refresh", "account": { "object": "tracking_account", "id": "tiktok_mia", "status": "ready", "refreshed_at": "2026-10-07T15:02:00.000Z" }, "throttled": false, "queued": 0 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getTrackedVideo", "method": "GET", "path": "/v1/tracking/accounts/{id}/videos/{video_id}", "group": "Creator Tracking", "summary": "Retrieve a tracked video", "description": "The app's video drawer. Always includes the daily snapshot `history`. `range` and `timezone` set the window for `views_gained`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Tracked account id: platform, underscore, lowercase handle (e.g. tiktok_mia).", "constraints": [] }, { "name": "video_id", "in": "path", "required": true, "type": "string", "description": "The platform's post id, as returned in a tracking_video's id.", "constraints": [] }, { "name": "range", "in": "query", "required": false, "type": "enum", "description": "Date range preset, same as the app's picker. Every range except all also has an equal-length previous period for deltas.", "default": "7d", "enum": [ "today", "yesterday", "7d", "30d", "last_month", "mtd", "ytd", "last_year", "all" ], "constraints": [] }, { "name": "timezone", "in": "query", "required": false, "type": "string", "description": "IANA time zone for day, week (Monday to Sunday) and month boundaries, e.g. America/New_York.", "default": "UTC", "constraints": [ "max length 64" ] } ], "body": null, "response": { "code": "200", "description": "The video with its history.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_video" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "The platform's post id.", "constraints": [] }, { "name": "account_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "caption", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "thumbnail_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "is_video", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "first_seen_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "saves", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "views_gained", "type": "integer | null", "required": false, "description": "Views gained inside the range.", "constraints": [] }, { "name": "prev_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "outlier_multiple", "type": "number | null", "required": false, "description": "Views divided by the creator's median video.", "constraints": [] }, { "name": "is_outlier", "type": "boolean", "required": false, "description": "3x or more and at least 1,000 views.", "constraints": [] }, { "name": "performance", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "growth", "type": "object", "required": false, "description": "Growth over 24 hours, 7, 14 and 30 days; null until a reading that old exists.", "constraints": [] }, { "name": "growth.h24", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "growth.d7", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "growth.d14", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "growth.d30", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "collection_name", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "history", "type": "object[]", "required": false, "description": "Daily snapshots. On the single-video endpoint always; on the list only with include_history=true.", "constraints": [] }, { "name": "history.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "history.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "history.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "history.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "history.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "history.saves", "type": "integer | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "refreshAllTracked", "method": "POST", "path": "/v1/tracking/refresh", "group": "Creator Tracking", "summary": "Refresh every tracked account", "description": "The app's \"Refresh all\". Queues every account not refreshed in the\nlast 10 minutes (up to 300, three at a time) and answers 202 right\naway with the number queued; numbers update over the next minutes.\n`throttled` is true when nothing needed queueing. No request body.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "202", "description": "The refresh was queued.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_refresh" ], "description": "", "constraints": [] }, { "name": "account", "type": "object | null", "required": false, "description": "The account (single refresh) or null (refresh all).", "constraints": [] }, { "name": "throttled", "type": "boolean", "required": false, "description": "True when stored data was returned or nothing was queued because of the 10 minute floor.", "constraints": [] }, { "name": "queued", "type": "integer", "required": false, "description": "Accounts queued by a refresh all; 0 for a single refresh.", "constraints": [] } ], "example": { "object": "tracking_refresh", "account": null, "throttled": false, "queued": 12 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "listTrackedVideos", "method": "GET", "path": "/v1/tracking/videos", "group": "Creator Tracking", "summary": "List tracked videos", "description": "The Videos table across every tracked account in scope.\n`outlier_multiple` is views divided by the creator's median video;\n`is_outlier` means 3x or more and at least 1,000 views. `growth.*`\nstays null until a reading that old exists. `thumbnail_url` goes\nthrough the app's media proxy. Add `include_history=true` for each\nvideo's daily snapshots. Triggers the background refresh-on-view.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "range", "in": "query", "required": false, "type": "enum", "description": "Date range preset, same as the app's picker. Every range except all also has an equal-length previous period for deltas.", "default": "7d", "enum": [ "today", "yesterday", "7d", "30d", "last_month", "mtd", "ytd", "last_year", "all" ], "constraints": [] }, { "name": "timezone", "in": "query", "required": false, "type": "string", "description": "IANA time zone for day, week (Monday to Sunday) and month boundaries, e.g. America/New_York.", "default": "UTC", "constraints": [ "max length 64" ] }, { "name": "collection_id", "in": "query", "required": false, "type": "string", "description": "Only accounts in this collection, and only posts matching its terms and date window. 404 collection_not_found if unknown.", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "account_ids", "in": "query", "required": false, "type": "string", "description": "Comma-separated tracked account ids (1 to 300), e.g. tiktok_mia,instagram_bea.", "constraints": [] }, { "name": "q", "in": "query", "required": false, "type": "string", "description": "Case-insensitive match on caption or handle.", "constraints": [ "min length 1", "max length 200" ] }, { "name": "uploaded_in_range", "in": "query", "required": false, "type": "boolean", "description": "Only videos posted inside the range, like the app's \"Uploaded in range only\" toggle.", "default": true, "constraints": [] }, { "name": "sort", "in": "query", "required": false, "type": "enum", "description": "", "default": "posted_at", "enum": [ "posted_at", "views", "views_gained", "outlier_multiple", "engagement_rate", "likes", "comments", "shares", "growth_24h", "growth_7d" ], "constraints": [] }, { "name": "order", "in": "query", "required": false, "type": "enum", "description": "", "default": "desc", "enum": [ "asc", "desc" ], "constraints": [] }, { "name": "include_history", "in": "query", "required": false, "type": "boolean", "description": "Include each video's daily snapshot history.", "default": false, "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of videos.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "tracking_video" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "The platform's post id.", "constraints": [] }, { "name": "data.account_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.caption", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.thumbnail_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "data.is_video", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data.duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.first_seen_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.saves", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.views_gained", "type": "integer | null", "required": false, "description": "Views gained inside the range.", "constraints": [] }, { "name": "data.prev_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.outlier_multiple", "type": "number | null", "required": false, "description": "Views divided by the creator's median video.", "constraints": [] }, { "name": "data.is_outlier", "type": "boolean", "required": false, "description": "3x or more and at least 1,000 views.", "constraints": [] }, { "name": "data.performance", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.growth", "type": "object", "required": false, "description": "Growth over 24 hours, 7, 14 and 30 days; null until a reading that old exists.", "constraints": [] }, { "name": "data.growth.h24", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.growth.d7", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.growth.d14", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.growth.d30", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.collection_name", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.history", "type": "object[]", "required": false, "description": "Daily snapshots. On the single-video endpoint always; on the list only with include_history=true.", "constraints": [] }, { "name": "data.history.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.history.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.history.saves", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "has_more": true, "next_cursor": "eyJvIjoyNSwi", "data": [ { "object": "tracking_video", "id": "7421", "account_id": "tiktok_mia", "platform": "tiktok", "handle": "mia", "url": "https://www.tiktok.com/@mia/video/7421", "caption": "morning routine #glow", "hashtags": [ "#glow" ], "thumbnail_url": "https://app.ugcagent.app/api/avatar?url=...&k=t&post=https%3A%2F%2Fwww.tiktok.com%2F%40mia%2Fvideo%2F7421", "is_video": true, "duration_s": 21, "posted_at": "2026-10-05T15:00:00.000Z", "views": 50000, "likes": 5000, "comments": 3, "shares": 1, "saves": null, "engagement_rate": 0.1001, "views_gained": 30500, "outlier_multiple": 41.6667, "is_outlier": true, "performance": "42X more views than usual", "growth": { "h24": 0.25, "d7": null, "d14": null, "d30": null }, "collection_id": "cmp_ab12cd34ef56", "collection_name": "Glow launch" } ] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getTrackingOverview", "method": "GET", "path": "/v1/tracking/overview", "group": "Creator Tracking", "summary": "Get the tracking overview", "description": "The Overview tab for the given filters: KPI totals against the\nprevious period of equal length, the main chart, most viral videos,\nvirality and duration analysis, top accounts, engagement breakdown,\nposting schedule, metrics breakdown and this week's payout summary.\n`metric` and `mode` drive the KPI values and chart exactly like the\napp's toggles. A `value` of null means not measured yet; `estimated:\ntrue` marks a total that counts some videos at their first reading.\nTriggers the background refresh-on-view.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "range", "in": "query", "required": false, "type": "enum", "description": "Date range preset, same as the app's picker. Every range except all also has an equal-length previous period for deltas.", "default": "7d", "enum": [ "today", "yesterday", "7d", "30d", "last_month", "mtd", "ytd", "last_year", "all" ], "constraints": [] }, { "name": "timezone", "in": "query", "required": false, "type": "string", "description": "IANA time zone for day, week (Monday to Sunday) and month boundaries, e.g. America/New_York.", "default": "UTC", "constraints": [ "max length 64" ] }, { "name": "collection_id", "in": "query", "required": false, "type": "string", "description": "Only accounts in this collection, and only posts matching its terms and date window. 404 collection_not_found if unknown.", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "account_ids", "in": "query", "required": false, "type": "string", "description": "Comma-separated tracked account ids (1 to 300), e.g. tiktok_mia,instagram_bea.", "constraints": [] }, { "name": "metric", "in": "query", "required": false, "type": "enum", "description": "", "default": "views", "enum": [ "views", "engagement", "likes", "comments", "shares", "saves" ], "constraints": [] }, { "name": "mode", "in": "query", "required": false, "type": "enum", "description": "total: value to date. per_day: gained per day.", "default": "total", "enum": [ "total", "per_day" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The overview.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_overview" ], "description": "", "constraints": [] }, { "name": "window", "type": "object", "required": false, "description": "The resolved date window.", "constraints": [] }, { "name": "window.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.timezone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_end", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "account_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "saves_available", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "kpis", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "kpis.metric", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "kpis.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "kpis.value", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "kpis.previous", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "kpis.change", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "chart", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "chart.metric", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "chart.mode", "type": "enum", "required": false, "enum": [ "total", "per_day" ], "description": "", "constraints": [] }, { "name": "chart.points", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "chart.points.date", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "chart.points.value", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "chart.points.uploads", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "chart.points.partial", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "chart.points.estimated", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "totals", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "totals.accounts", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "totals.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "totals.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "totals.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "totals.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "totals.spend", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "totals.cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "totals.cpe", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "totals.paid_accounts", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos", "type": "object[]", "required": false, "description": "Top 3 by outlier multiple.", "constraints": [] }, { "name": "most_viral_videos.object", "type": "enum", "required": false, "enum": [ "tracking_video" ], "description": "", "constraints": [] }, { "name": "most_viral_videos.id", "type": "string", "required": false, "description": "The platform's post id.", "constraints": [] }, { "name": "most_viral_videos.account_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "most_viral_videos.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.caption", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.thumbnail_url", "type": "string | null", "required": false, "description": "Served through the app media proxy so it does not expire.", "constraints": [] }, { "name": "most_viral_videos.is_video", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.first_seen_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.saves", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.engagements", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.engagement_rate", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.views_gained", "type": "integer | null", "required": false, "description": "Views gained inside the range.", "constraints": [] }, { "name": "most_viral_videos.prev_views", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.outlier_multiple", "type": "number | null", "required": false, "description": "Views divided by the creator's median video.", "constraints": [] }, { "name": "most_viral_videos.is_outlier", "type": "boolean", "required": false, "description": "3x or more and at least 1,000 views.", "constraints": [] }, { "name": "most_viral_videos.performance", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.growth", "type": "object", "required": false, "description": "Growth over 24 hours, 7, 14 and 30 days; null until a reading that old exists.", "constraints": [] }, { "name": "most_viral_videos.growth.h24", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.growth.d7", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.growth.d14", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.growth.d30", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.collection_name", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.history", "type": "object[]", "required": false, "description": "Daily snapshots. On the single-video endpoint always; on the list only with include_history=true.", "constraints": [] }, { "name": "most_viral_videos.history.at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.history.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.history.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.history.comments", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.history.shares", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "most_viral_videos.history.saves", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "virality", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "virality.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "virality.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "virality.min_multiple", "type": "number", "required": false, "description": "", "constraints": [] }, { "name": "virality.max_multiple", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "virality.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "virality.share", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.avg_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.median_views", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.buckets.best", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "duration_analysis.optimal_duration_s", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "top_accounts", "type": "object[]", "required": false, "description": "Top 6 by views.", "constraints": [] }, { "name": "engagement_breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown.id", "type": "enum", "required": false, "enum": [ "likes", "comments", "shares", "saves" ], "description": "", "constraints": [] }, { "name": "engagement_breakdown.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "engagement_breakdown.value", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "posting_schedule", "type": "object", "required": false, "description": "weekdays, day_parts and a grid of {uploads, median_views} cells.", "constraints": [] }, { "name": "metrics_breakdown", "type": "object", "required": false, "description": "by_day (newest first, up to 30 days), by_day_average, averages (daily, weekly, last 28 days) and upload_activity (20 Monday to Sunday weeks, null for future days).", "constraints": [] }, { "name": "payouts", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "payouts.week_start", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "payouts.total_payout", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "payouts.spend_in_range", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "payouts.blended_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "payouts.target_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "payouts.accounts", "type": "integer", "required": false, "description": "", "constraints": [] } ], "example": { "object": "tracking_overview", "window": { "key": "7d", "label": "Last 7 days", "timezone": "UTC", "start": "2026-10-01T00:00:00.000Z", "end": "2026-10-07T15:00:00.000Z", "previous_start": "2026-09-24T00:00:00.000Z", "previous_end": "2026-10-01T00:00:00.000Z" }, "collection_id": null, "account_count": 42, "saves_available": true, "kpis": [ { "metric": "views", "label": "Views", "value": 1250000, "previous": 980000, "change": 0.2755 } ], "chart": { "metric": "views", "mode": "total", "points": [ { "date": "2026-10-01T00:00:00.000Z", "value": 1100000, "uploads": 4, "partial": false, "estimated": false } ] }, "totals": { "accounts": 42, "videos": 61, "views": 1250000, "engagements": 98000, "engagement_rate": 0.0784, "spend": 4200, "cpm": 6.2, "cpe": 0.07, "paid_accounts": 9 }, "payouts": { "week_start": "2026-10-05T00:00:00.000Z", "total_payout": 1800, "spend_in_range": 4200, "blended_cpm": 6.2, "target_cpm": null, "accounts": 9 } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "getTrackingPayouts", "method": "GET", "path": "/v1/tracking/payouts", "group": "Creator Tracking", "summary": "Get this week's payouts", "description": "The Payouts module: accounts with a fee and what they earn for the\ncurrent week (Monday 00:00 in `timezone` until now). `range` only sets\n`spend_in_range` and `blended_cpm`. Set fees and payout status with\nPATCH /v1/tracking/accounts/{id}. Triggers the background\nrefresh-on-view.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "range", "in": "query", "required": false, "type": "enum", "description": "Date range preset, same as the app's picker. Every range except all also has an equal-length previous period for deltas.", "default": "7d", "enum": [ "today", "yesterday", "7d", "30d", "last_month", "mtd", "ytd", "last_year", "all" ], "constraints": [] }, { "name": "timezone", "in": "query", "required": false, "type": "string", "description": "IANA time zone for day, week (Monday to Sunday) and month boundaries, e.g. America/New_York.", "default": "UTC", "constraints": [ "max length 64" ] }, { "name": "collection_id", "in": "query", "required": false, "type": "string", "description": "Only accounts in this collection, and only posts matching its terms and date window. 404 collection_not_found if unknown.", "constraints": [] }, { "name": "platform", "in": "query", "required": false, "type": "enum", "description": "", "enum": [ "instagram", "tiktok" ], "constraints": [] }, { "name": "account_ids", "in": "query", "required": false, "type": "string", "description": "Comma-separated tracked account ids (1 to 300), e.g. tiktok_mia,instagram_bea.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "This week's payouts.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_payouts" ], "description": "", "constraints": [] }, { "name": "week_start", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "week_end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window", "type": "object", "required": false, "description": "The resolved date window.", "constraints": [] }, { "name": "window.key", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.label", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.timezone", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.end", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_start", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "window.previous_end", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "collection_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "total_payout", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "spend_in_range", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "blended_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "target_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "tracking_payout" ], "description": "", "constraints": [] }, { "name": "data.account_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "data.fee", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.fee_basis", "type": "enum", "required": false, "enum": [ "flat", "per_video", "cpm" ], "description": "", "constraints": [] }, { "name": "data.payout_status", "type": "enum", "required": false, "enum": [ "none", "pending", "approved", "paid", "assumed_paid" ], "description": "", "constraints": [] }, { "name": "data.videos", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.views_gained", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.views_on_period_posts", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.base_pay", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.cpm_pay", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.total_payout", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.weekly_quota", "type": "object | null", "required": false, "description": "Posting target progress for this week, from the account's own collection posts_per_week. Null without one.", "constraints": [] }, { "name": "data.weekly_quota.posted", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.weekly_quota.expected", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.weekly_quota.ratio", "type": "number", "required": false, "description": "", "constraints": [] } ], "example": { "object": "tracking_payouts", "week_start": "2026-10-05T00:00:00.000Z", "week_end": "2026-10-07T15:00:00.000Z", "collection_id": "cmp_ab12cd34ef56", "total_payout": 600, "spend_in_range": 400, "blended_cpm": 7.84, "target_cpm": 12.5, "data": [ { "object": "tracking_payout", "account_id": "tiktok_mia", "handle": "mia", "platform": "tiktok", "fee": 200, "fee_basis": "per_video", "payout_status": "approved", "videos": 1, "views_gained": 30500, "views_on_period_posts": 50000, "base_pay": 200, "cpm_pay": 0, "total_payout": 200, "weekly_quota": { "posted": 1, "expected": 3, "ratio": 0.3333 } } ] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "listTrackingCollections", "method": "GET", "path": "/v1/tracking/collections", "group": "Creator Tracking", "summary": "List collections", "description": "Tracking collections (the app's campaigns), newest first.", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of collections.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "tracking_collection" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Prefixed cmp_.", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.match_terms", "type": "string[]", "required": false, "description": "Stored trimmed, lowercased and de-duplicated.", "constraints": [] }, { "name": "data.starts_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.ends_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.target_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.budget", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "data.posts_per_week", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.account_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "data.created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "createTrackingCollection", "method": "POST", "path": "/v1/tracking/collections", "group": "Creator Tracking", "summary": "Create a collection", "description": "A collection groups tracked accounts into a campaign. Only posts whose\ncaption contains one of `match_terms` (for example `#brand`) and that\nfall between `starts_at` and `ends_at` count toward it; with no terms,\nevery post in the window counts. `ends_at` counts through the end of\nthat day. A bare date is read as UTC midnight; send a timestamp with\nan offset to match a local day. Send an `Idempotency-Key` to make\nretries safe: a replay answers 200 with the same collection.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "name", "type": "string", "required": true, "example": "Glow launch", "description": "", "constraints": [ "min length 1", "max length 80" ] }, { "name": "match_terms", "type": "string[]", "required": false, "example": [ "#glow" ], "description": "Caption terms a post must contain to count. Empty: every post in the window counts.", "constraints": [ "max 20 items" ] }, { "name": "starts_at", "type": "string | null", "required": false, "example": "2026-09-01T00:00:00-04:00", "description": "ISO 8601 date or timestamp.", "constraints": [] }, { "name": "ends_at", "type": "string | null", "required": false, "description": "ISO 8601; counts through the end of that day. Must not be before starts_at.", "constraints": [] }, { "name": "target_cpm", "type": "number | null", "required": false, "example": 12.5, "description": "", "constraints": [ "min 0", "max 10000000" ] }, { "name": "budget", "type": "number | null", "required": false, "example": 5000, "description": "", "constraints": [ "min 0", "max 10000000" ] }, { "name": "posts_per_week", "type": "integer | null", "required": false, "example": 3, "description": "Weekly posting target per account.", "constraints": [ "min 0", "max 100" ] } ], "example": { "name": "Glow launch", "match_terms": [ "#glow" ], "starts_at": "2026-09-01T00:00:00-04:00", "ends_at": null, "target_cpm": 12.5, "budget": 5000, "posts_per_week": 3 } }, "response": { "code": "200", "description": "Idempotent replay of an earlier create.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_collection" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Prefixed cmp_.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "match_terms", "type": "string[]", "required": false, "description": "Stored trimmed, lowercased and de-duplicated.", "constraints": [] }, { "name": "starts_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "ends_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "target_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "budget", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "posts_per_week", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "account_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getTrackingCollection", "method": "GET", "path": "/v1/tracking/collections/{id}", "group": "Creator Tracking", "summary": "Retrieve a collection", "description": "", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Collection id, prefixed cmp_.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The collection.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_collection" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Prefixed cmp_.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "match_terms", "type": "string[]", "required": false, "description": "Stored trimmed, lowercased and de-duplicated.", "constraints": [] }, { "name": "starts_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "ends_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "target_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "budget", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "posts_per_week", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "account_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "updateTrackingCollection", "method": "PATCH", "path": "/v1/tracking/collections/{id}", "group": "Creator Tracking", "summary": "Update a collection", "description": "Changes any subset of the collection's fields (at least one, 400 `empty_update` otherwise). Accepts an `Idempotency-Key`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Collection id, prefixed cmp_.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "name", "type": "string", "required": false, "example": "Glow launch", "description": "", "constraints": [ "min length 1", "max length 80" ] }, { "name": "match_terms", "type": "string[]", "required": false, "example": [ "#glow" ], "description": "", "constraints": [ "max 20 items" ] }, { "name": "starts_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "ends_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "target_cpm", "type": "number | null", "required": false, "example": 10, "description": "", "constraints": [ "min 0", "max 10000000" ] }, { "name": "budget", "type": "number | null", "required": false, "description": "", "constraints": [ "min 0", "max 10000000" ] }, { "name": "posts_per_week", "type": "integer | null", "required": false, "example": 4, "description": "", "constraints": [ "min 0", "max 100" ] } ], "example": { "target_cpm": 10, "posts_per_week": 4 } }, "response": { "code": "200", "description": "The updated collection.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "tracking_collection" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Prefixed cmp_.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "match_terms", "type": "string[]", "required": false, "description": "Stored trimmed, lowercased and de-duplicated.", "constraints": [] }, { "name": "starts_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "ends_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "target_cpm", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "budget", "type": "number | null", "required": false, "description": "", "constraints": [] }, { "name": "posts_per_week", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "account_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "deleteTrackingCollection", "method": "DELETE", "path": "/v1/tracking/collections/{id}", "group": "Creator Tracking", "summary": "Delete a collection", "description": "Deletes the collection. Its accounts stay tracked without a collection. Accepts an `Idempotency-Key`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Collection id, prefixed cmp_.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "204", "description": "Deleted.", "fields": [], "example": null }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] } ] }, { "name": "Applications", "endpoints": [ { "id": "listApplications", "method": "GET", "path": "/v1/applications", "group": "Applications", "summary": "List applications", "description": "The creator applications imported into this workspace (the same\nrecords the app's chat agent lists), ordered by `score` descending,\nthen newest import first. Filter by `status`. Cursor pagination\nreaches every application. A review re-scores applications and can\nreorder them between pages.\n\nApplications belong to the user who imported them. An API key acts on\nthe applications of the team member who created the key (the workspace\nowner for keys created before member attribution).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "status", "in": "query", "required": false, "type": "enum", "description": "Only applications in this status.", "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 25, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page (an application id).", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of applications.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "application" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Application id, prefixed app_.", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "description": "Where the applicant is in your review. Only changed by you, never by a review.", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.instagram", "type": "string | null", "required": false, "description": "Instagram handle without the @.", "constraints": [] }, { "name": "data.tiktok", "type": "string | null", "required": false, "description": "TikTok handle without the @.", "constraints": [] }, { "name": "data.location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.rate", "type": "string | null", "required": false, "description": "Rate as the applicant wrote it.", "constraints": [] }, { "name": "data.availability", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.video_urls", "type": "string[]", "required": false, "description": "Sample video links found in the application.", "constraints": [] }, { "name": "data.answers", "type": "object", "required": false, "description": "Every form question and answer, keyed by question.", "constraints": [] }, { "name": "data.score", "type": "integer", "required": false, "description": "Heuristic fit score from the latest review or import.", "constraints": [ "min 0", "max 100" ] }, { "name": "data.recommendation", "type": "enum", "required": false, "enum": [ "strong_accept", "shortlist", "review", "reject" ], "description": "Suggested next step. A recommendation, not a decision.", "constraints": [] }, { "name": "data.review_notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.risk_flags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.matched_criteria", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.account_analysis", "type": "object | null", "required": false, "description": "Public account analysis (followers, views, engagement, viral score, top posts), present after a review with analyze_accounts.", "constraints": [] }, { "name": "data.video_analysis", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.source", "type": "string", "required": false, "description": "Where the row came from: the import source label or file name.", "constraints": [] }, { "name": "data.imported_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "application", "id": "app_4f1c9a2b7e3d5c8a1b", "status": "new", "name": "Alex Rivera", "email": "alex@example.com", "instagram": "alexugc", "tiktok": null, "location": "Austin", "niche": "skincare", "followers": 12000, "rate": "$150 per video", "availability": "weekly", "portfolio_url": "https://alex.example.com", "video_urls": [], "answers": { "Why do you want to join?": "I already use the serum daily." }, "score": 82, "recommendation": "strong_accept", "review_notes": [ "Strong fit. Prioritize for manual approval." ], "risk_flags": [], "matched_criteria": [ "skincare" ], "account_analysis": null, "video_analysis": null, "source": "API import", "imported_at": "2026-10-07T12:00:00.000Z", "updated_at": "2026-10-07T12:05:00.000Z" } ], "has_more": false, "next_cursor": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getApplication", "method": "GET", "path": "/v1/applications/{id}", "group": "Applications", "summary": "Retrieve an application", "description": "One application with its full answers, account analysis and video analysis. Unknown ids answer 404 `application_not_found`.", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Application id, e.g. app_4f1c9a2b7e3d5c8a1b.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The application.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Application id, prefixed app_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "description": "Where the applicant is in your review. Only changed by you, never by a review.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "instagram", "type": "string | null", "required": false, "description": "Instagram handle without the @.", "constraints": [] }, { "name": "tiktok", "type": "string | null", "required": false, "description": "TikTok handle without the @.", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "rate", "type": "string | null", "required": false, "description": "Rate as the applicant wrote it.", "constraints": [] }, { "name": "availability", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "video_urls", "type": "string[]", "required": false, "description": "Sample video links found in the application.", "constraints": [] }, { "name": "answers", "type": "object", "required": false, "description": "Every form question and answer, keyed by question.", "constraints": [] }, { "name": "score", "type": "integer", "required": false, "description": "Heuristic fit score from the latest review or import.", "constraints": [ "min 0", "max 100" ] }, { "name": "recommendation", "type": "enum", "required": false, "enum": [ "strong_accept", "shortlist", "review", "reject" ], "description": "Suggested next step. A recommendation, not a decision.", "constraints": [] }, { "name": "review_notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "risk_flags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "matched_criteria", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "account_analysis", "type": "object | null", "required": false, "description": "Public account analysis (followers, views, engagement, viral score, top posts), present after a review with analyze_accounts.", "constraints": [] }, { "name": "video_analysis", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "source", "type": "string", "required": false, "description": "Where the row came from: the import source label or file name.", "constraints": [] }, { "name": "imported_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "updateApplicationStatus", "method": "PATCH", "path": "/v1/applications/{id}", "group": "Applications", "summary": "Update an application's status", "description": "Moves one application to a new status, as the app does when you ask\nthe agent to shortlist, accept or reject someone. Nothing is sent to\nthe applicant. To change many at once use\nPOST /v1/application-status-updates. Accepts `Idempotency-Key`; a\nreplay answers with `Idempotency-Replayed: true`.\n\nErrors: `missing_status`, `invalid_status`, `unknown_parameter` (400);\n`application_not_found` (404); `idempotency_conflict` (409).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "Application id, e.g. app_4f1c9a2b7e3d5c8a1b.", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "status", "type": "enum", "required": true, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "example": "shortlisted", "description": "The new status.", "constraints": [] } ], "example": { "status": "shortlisted" } }, "response": { "code": "200", "description": "The updated application.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Application id, prefixed app_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "description": "Where the applicant is in your review. Only changed by you, never by a review.", "constraints": [] }, { "name": "name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "instagram", "type": "string | null", "required": false, "description": "Instagram handle without the @.", "constraints": [] }, { "name": "tiktok", "type": "string | null", "required": false, "description": "TikTok handle without the @.", "constraints": [] }, { "name": "location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "rate", "type": "string | null", "required": false, "description": "Rate as the applicant wrote it.", "constraints": [] }, { "name": "availability", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "video_urls", "type": "string[]", "required": false, "description": "Sample video links found in the application.", "constraints": [] }, { "name": "answers", "type": "object", "required": false, "description": "Every form question and answer, keyed by question.", "constraints": [] }, { "name": "score", "type": "integer", "required": false, "description": "Heuristic fit score from the latest review or import.", "constraints": [ "min 0", "max 100" ] }, { "name": "recommendation", "type": "enum", "required": false, "enum": [ "strong_accept", "shortlist", "review", "reject" ], "description": "Suggested next step. A recommendation, not a decision.", "constraints": [] }, { "name": "review_notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "risk_flags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "matched_criteria", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "account_analysis", "type": "object | null", "required": false, "description": "Public account analysis (followers, views, engagement, viral score, top posts), present after a review with analyze_accounts.", "constraints": [] }, { "name": "video_analysis", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "source", "type": "string", "required": false, "description": "Where the row came from: the import source label or file name.", "constraints": [] }, { "name": "imported_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "bulkUpdateApplicationStatus", "method": "POST", "path": "/v1/application-status-updates", "group": "Applications", "summary": "Update many statuses", "description": "Sets one status on up to 250 applications. Ids that do not exist are\nignored, as in the app, so `updated` can be lower than the number of\nids sent. Nothing is sent to the applicants. Accepts `Idempotency-Key`.\n\nErrors: `invalid_application_ids`, `missing_status`, `invalid_status`\n(400); `idempotency_conflict` (409).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "application_ids", "type": "string[]", "required": true, "example": [ "app_4f1c9a2b7e3d5c8a1b" ], "description": "Applications to update.", "constraints": [ "min 1 items", "max 250 items" ] }, { "name": "status", "type": "enum", "required": true, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "example": "rejected", "description": "The new status.", "constraints": [] } ], "example": { "application_ids": [ "app_4f1c9a2b7e3d5c8a1b", "app_9d2e7f1a3c5b8e4d6f" ], "status": "rejected" } }, "response": { "code": "200", "description": "How many applications changed.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application_status_update" ], "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "description": "", "constraints": [] }, { "name": "updated", "type": "integer", "required": false, "description": "Applications that changed. Unknown ids are ignored.", "constraints": [] } ], "example": { "object": "application_status_update", "status": "rejected", "updated": 2 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "importApplications", "method": "POST", "path": "/v1/application-imports", "group": "Applications", "summary": "Import applications", "description": "Imports applicants from a form export (Typeform, Google Forms, Tally\nor any CSV), the same parser the app's chat upload uses. Two ways to\nsend it:\n\n- JSON: `csv` holds the CSV or plain-text content (at most 4,194,304\n characters), with optional `source` and `criteria`.\n- `multipart/form-data`: a `file` part (CSV, TXT or text-based PDF, at\n most 8 MB) plus optional `source` and `criteria` text fields.\n `source` defaults to the file name.\n\nUp to 1,000 rows per import. Rows are matched to existing applicants\nby email, handle or name, so re-importing updates them (keeping their\nstatus) instead of creating duplicates. `criteria` (at most 5,000\ncharacters) pre-scores the imported rows. `source` defaults to\n\"API import\" for JSON bodies. Accepts `Idempotency-Key`.\n\nErrors: `invalid_csv`, `missing_file`, `invalid_source`,\n`invalid_criteria`, `invalid_multipart`, `unknown_parameter` (400);\n`file_too_large` (413); `file_unreadable` (422, a scanned or corrupt\nPDF); `idempotency_conflict` (409).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "csv", "type": "string", "required": true, "description": "CSV or plain-text export content. Up to 1,000 rows.", "constraints": [ "min length 1", "max length 4194304" ] }, { "name": "source", "type": "string", "required": false, "default": "API import", "example": "Typeform October", "description": "Label stored on each application.", "constraints": [ "max length 200" ] }, { "name": "criteria", "type": "string", "required": false, "example": "skincare, US based, at least one sample video", "description": "Program criteria used to pre-score the rows.", "constraints": [ "max length 5000" ] } ], "example": { "csv": "Name,Email,Instagram,Niche,Followers,Rate\nAlex Rivera,alex@example.com,alexugc,skincare,12000,$150 per video", "source": "Typeform October", "criteria": "skincare, US based, at least one sample video" } }, "response": { "code": "200", "description": "The import result with the imported or updated applications.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application_import" ], "description": "", "constraints": [] }, { "name": "imported", "type": "integer", "required": false, "description": "New applicants created.", "constraints": [] }, { "name": "updated", "type": "integer", "required": false, "description": "Existing applicants matched and updated.", "constraints": [] }, { "name": "skipped", "type": "integer", "required": false, "description": "Rows with no usable applicant data.", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "application" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Application id, prefixed app_.", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "description": "Where the applicant is in your review. Only changed by you, never by a review.", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.instagram", "type": "string | null", "required": false, "description": "Instagram handle without the @.", "constraints": [] }, { "name": "data.tiktok", "type": "string | null", "required": false, "description": "TikTok handle without the @.", "constraints": [] }, { "name": "data.location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.rate", "type": "string | null", "required": false, "description": "Rate as the applicant wrote it.", "constraints": [] }, { "name": "data.availability", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.video_urls", "type": "string[]", "required": false, "description": "Sample video links found in the application.", "constraints": [] }, { "name": "data.answers", "type": "object", "required": false, "description": "Every form question and answer, keyed by question.", "constraints": [] }, { "name": "data.score", "type": "integer", "required": false, "description": "Heuristic fit score from the latest review or import.", "constraints": [ "min 0", "max 100" ] }, { "name": "data.recommendation", "type": "enum", "required": false, "enum": [ "strong_accept", "shortlist", "review", "reject" ], "description": "Suggested next step. A recommendation, not a decision.", "constraints": [] }, { "name": "data.review_notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.risk_flags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.matched_criteria", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.account_analysis", "type": "object | null", "required": false, "description": "Public account analysis (followers, views, engagement, viral score, top posts), present after a review with analyze_accounts.", "constraints": [] }, { "name": "data.video_analysis", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.source", "type": "string", "required": false, "description": "Where the row came from: the import source label or file name.", "constraints": [] }, { "name": "data.imported_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ], "example": { "object": "application_import", "imported": 1, "updated": 0, "skipped": 0, "data": [] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "413", "description": "The uploaded file is larger than 8 MB (file_too_large)." }, { "code": "422", "description": "The uploaded file could not be read (file_unreadable). Send a CSV, TXT or text-based PDF." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "reviewApplications", "method": "POST", "path": "/v1/application-reviews", "group": "Applications", "summary": "Review applications", "description": "Scores and ranks applications against your program criteria and\nwrites `score`, `recommendation`, `review_notes`, `risk_flags` and\n`matched_criteria` back onto each one. A review recommends only: it\nnever changes a status and never contacts anyone.\n\nSend `application_ids` to review specific applications, or omit them\nto review the most recently imported ones up to `limit`. Results come\nback sorted by score, highest first.\n\n`analyze_accounts: true` also fetches each applicant's public\nInstagram or TikTok account and stores the result in\n`account_analysis`. It runs synchronously, so keep `limit` small\n(25 or fewer), and it consumes one job-creating call from the\nworkspace quota (the response then carries the X-Quota headers).\nPlain re-scoring consumes none. Accepts `Idempotency-Key`; a replay\nis not charged again.\n\nErrors: `invalid_application_ids`, `invalid_criteria`,\n`invalid_analyze_accounts`, `invalid_limit` (400);\n`idempotency_conflict` (409); `api_daily_quota_exceeded` /\n`api_monthly_quota_exceeded` (429, only with `analyze_accounts`).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "application_ids", "type": "string[]", "required": false, "description": "Review these applications. Omit to review the most recently imported ones up to limit.", "constraints": [ "max 250 items" ] }, { "name": "criteria", "type": "string", "required": false, "example": "skincare, US based, at least one sample video", "description": "Program criteria to score against.", "constraints": [ "max length 5000" ] }, { "name": "analyze_accounts", "type": "boolean", "required": false, "default": false, "example": false, "description": "Also analyze each applicant's public Instagram or TikTok account. Slower; consumes one job-creating call.", "constraints": [] }, { "name": "limit", "type": "integer", "required": false, "default": 100, "example": 50, "description": "Most applications to review.", "constraints": [ "min 1", "max 250" ] } ], "example": { "criteria": "skincare, US based, at least one sample video", "analyze_accounts": false, "limit": 50 } }, "response": { "code": "200", "description": "The reviewed applications, highest score first.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application_review" ], "description": "", "constraints": [] }, { "name": "reviewed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "analyze_accounts", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "Reviewed applications, highest score first.", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "application" ], "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Application id, prefixed app_.", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "new", "shortlisted", "rejected", "accepted", "contacted" ], "description": "Where the applicant is in your review. Only changed by you, never by a review.", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.email", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.instagram", "type": "string | null", "required": false, "description": "Instagram handle without the @.", "constraints": [] }, { "name": "data.tiktok", "type": "string | null", "required": false, "description": "TikTok handle without the @.", "constraints": [] }, { "name": "data.location", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.niche", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.followers", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "data.rate", "type": "string | null", "required": false, "description": "Rate as the applicant wrote it.", "constraints": [] }, { "name": "data.availability", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.portfolio_url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.video_urls", "type": "string[]", "required": false, "description": "Sample video links found in the application.", "constraints": [] }, { "name": "data.answers", "type": "object", "required": false, "description": "Every form question and answer, keyed by question.", "constraints": [] }, { "name": "data.score", "type": "integer", "required": false, "description": "Heuristic fit score from the latest review or import.", "constraints": [ "min 0", "max 100" ] }, { "name": "data.recommendation", "type": "enum", "required": false, "enum": [ "strong_accept", "shortlist", "review", "reject" ], "description": "Suggested next step. A recommendation, not a decision.", "constraints": [] }, { "name": "data.review_notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.risk_flags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.matched_criteria", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "data.account_analysis", "type": "object | null", "required": false, "description": "Public account analysis (followers, views, engagement, viral score, top posts), present after a review with analyze_accounts.", "constraints": [] }, { "name": "data.video_analysis", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "data.source", "type": "string", "required": false, "description": "Where the row came from: the import source label or file name.", "constraints": [] }, { "name": "data.imported_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.updated_at", "type": "string", "required": false, "description": "", "constraints": [] } ], "example": { "object": "application_review", "reviewed": 2, "analyze_accounts": false, "data": [] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "draftApplicationResponse", "method": "POST", "path": "/v1/application-response-drafts", "group": "Applications", "summary": "Draft a reply", "description": "Drafts an accept, reject or shortlist reply for one applicant, the\nsame template the app's agent uses. Returns text only: nothing is\nsent and the application's status does not change. Accepts\n`Idempotency-Key`.\n\nErrors: `invalid_application_id`, `invalid_decision` (400);\n`application_not_found` (404); `idempotency_conflict` (409).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "application_id", "type": "string", "required": true, "example": "app_4f1c9a2b7e3d5c8a1b", "description": "The applicant to reply to.", "constraints": [] }, { "name": "decision", "type": "enum", "required": true, "enum": [ "accept", "reject", "shortlist" ], "example": "accept", "description": "Which reply to draft.", "constraints": [] } ], "example": { "application_id": "app_4f1c9a2b7e3d5c8a1b", "decision": "accept" } }, "response": { "code": "200", "description": "The draft.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application_response_draft" ], "description": "", "constraints": [] }, { "name": "application_id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "decision", "type": "enum", "required": false, "enum": [ "accept", "reject", "shortlist" ], "description": "", "constraints": [] }, { "name": "draft", "type": "string", "required": false, "description": "Reply text. Never sent by UGC Agent.", "constraints": [] } ], "example": { "object": "application_response_draft", "application_id": "app_4f1c9a2b7e3d5c8a1b", "decision": "accept", "draft": "Hi Alex,\n\nThanks for applying..." } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "analyzeApplicationVideo", "method": "POST", "path": "/v1/application-video-analyses", "group": "Applications", "summary": "Analyze a sample video", "description": "Analyzes a UGC sample video the way the app does when you drop an MP4\ninto the chat: hook, on-screen text, visual beats, pacing, strengths,\nrisks, suggested edits and a score.\n\nSend `multipart/form-data` (JSON is refused with\n`invalid_content_type`) with these parts:\n- `file` (required): the video, any `video/*` type such as\n video/mp4, at most 100 MB.\n- `application_id` (optional): attach the analysis to that\n application and re-score it. The id is checked before the video is\n analyzed.\n- `context` (optional, at most 2,000 characters): program context for\n the analysis, such as the product and what the brief asks for.\n\nConsumes one job-creating call from the workspace quota and carries\nthe X-Quota headers. Accepts `Idempotency-Key`; a replay is not\ncharged again.\n\nErrors: `invalid_content_type`, `missing_file`, `invalid_file_type`,\n`invalid_application_id`, `invalid_context`, `invalid_multipart`,\n`unknown_parameter` (400); `application_not_found` (404);\n`file_too_large` (413); `idempotency_conflict` (409);\n`api_daily_quota_exceeded` / `api_monthly_quota_exceeded` (429).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "200", "description": "The analysis, and the re-scored application when `application_id` was sent.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "application_video_analysis" ], "description": "", "constraints": [] }, { "name": "application_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "analysis", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "analysis.summary", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "analysis.hook", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "analysis.on_screen_text", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "analysis.visual_beats", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "analysis.pacing", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "analysis.ugc_strengths", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "analysis.risks", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "analysis.suggested_edits", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "analysis.score", "type": "number", "required": false, "description": "Overall UGC quality score, 0 to 100.", "constraints": [] }, { "name": "application", "type": "object | null", "required": false, "description": "The re-scored application when application_id was sent, otherwise null.", "constraints": [] } ], "example": { "object": "application_video_analysis", "application_id": "app_4f1c9a2b7e3d5c8a1b", "analysis": { "summary": "Bathroom shelf routine with a clear before and after.", "hook": "\"I stopped buying five serums for this one.\"", "on_screen_text": [ "3 weeks in" ], "visual_beats": [ "Shelf clear-out", "Product close-up", "Result selfie" ], "pacing": "Fast first 3 seconds, steady after.", "ugc_strengths": [ "Natural lighting", "Product visible early" ], "risks": [ "No captions" ], "suggested_edits": [ "Add captions for sound-off viewers" ], "score": 77 }, "application": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "413", "description": "The video is larger than 100 MB (file_too_large)." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] } ] }, { "name": "Outreach Integrations", "endpoints": [ { "id": "listOutreachIntegrations", "method": "GET", "path": "/v1/integrations", "group": "Outreach Integrations", "summary": "List outreach integrations", "description": "Instantly and Smartlead, with whether each is connected for the acting\nuser and the campaign they last sent to. Connecting or disconnecting a\nvendor key happens in the app under Integrations; the API never\naccepts, stores or returns a vendor key.\n\nOutreach calls share the `integrations` rate bucket (60 requests per\nminute per key and workspace) and never consume the API call quota or\nleads. No query parameters (unknown ones answer 400\n`unknown_parameter`).\n", "deprecated": false, "comingSoon": false, "params": [], "body": null, "response": { "code": "200", "description": "Both integrations, connected or not.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.id", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "integration" ], "description": "", "constraints": [] }, { "name": "data.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "data.name", "type": "enum", "required": false, "enum": [ "Instantly", "Smartlead" ], "description": "", "constraints": [] }, { "name": "data.connected", "type": "boolean", "required": false, "description": "Whether the acting user has a vendor key connected in the app.", "constraints": [] }, { "name": "data.connected_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.last_validated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "data.last_used_campaign", "type": "object | null", "required": false, "description": "The campaign leads were last sent to from the app or the API.", "constraints": [] }, { "name": "data.last_used_campaign.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.last_used_campaign.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.last_used_campaign.status", "type": "enum", "required": false, "enum": [ "draft", "active", "paused", "completed", "running_subsequences", "accounts_unhealthy", "bounce_protect", "account_suspended", "stopped", "archived", "unknown" ], "description": "One vocabulary across vendors. Smartlead states outside this list are passed through lower-cased.", "constraints": [] }, { "name": "data.last_used_campaign.selected_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "Always false.", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "Always null.", "constraints": [] } ], "example": { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "id": "instantly", "object": "integration", "provider": "instantly", "name": "Instantly", "connected": true, "connected_at": "2026-10-01T09:00:00.000Z", "last_validated_at": "2026-10-01T09:00:00.000Z", "last_used_campaign": { "id": "8c2f6a1e-4b7d-4f1a-9c3e-2d5b7a9e1f00", "name": "Summer UGC", "status": "active", "selected_at": "2026-10-03T12:00:00.000Z" } }, { "id": "smartlead", "object": "integration", "provider": "smartlead", "name": "Smartlead", "connected": false, "connected_at": null, "last_validated_at": null, "last_used_campaign": null } ] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getAutoSend", "method": "GET", "path": "/v1/integrations/auto-send", "group": "Outreach Integrations", "summary": "Retrieve auto-send", "description": "The app's auto-send setting. When enabled, every new eligible lead from\nchat searches (web app and the hosted MCP's `run_ugc_agent`),\nautomation runs and applications is sent to the chosen campaign\nautomatically. It does not fire for `/v1/creator-searches` or\n`/v1/messages`. A user who never configured it gets `enabled: false`\nwith every other field null.\n", "deprecated": false, "comingSoon": false, "params": [], "body": null, "response": { "code": "200", "description": "The auto-send setting.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "auto_send" ], "description": "", "constraints": [] }, { "name": "enabled", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead", null ], "description": "", "constraints": [] }, { "name": "campaign", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "campaign.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "campaign.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "selected_at", "type": "string | null", "required": false, "description": "When the campaign was chosen.", "constraints": [] }, { "name": "updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "auto_send", "enabled": true, "provider": "instantly", "campaign": { "id": "8c2f6a1e-4b7d-4f1a-9c3e-2d5b7a9e1f00", "name": "Summer UGC" }, "selected_at": "2026-10-03T12:00:00.000Z", "updated_at": "2026-10-03T12:00:00.000Z" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "updateAutoSend", "method": "PATCH", "path": "/v1/integrations/auto-send", "group": "Outreach Integrations", "summary": "Update auto-send", "description": "Turns auto-send on or off, or points it at another campaign.\n- `{enabled: true, provider, campaign_id}` arms it on that campaign.\n The campaign is checked with the vendor (it must exist and accept\n leads) and its name is stored.\n- `{enabled: true}` re-arms the previously chosen campaign (400\n `auto_send_not_configured` if there is none).\n- `{enabled: false}` disarms it and keeps the provider and campaign.\n\n`provider` and `campaign_id` are only accepted while enabling, and\nonly together. Errors: 400 `invalid_enabled`, `invalid_auto_send`,\n`invalid_provider`, `invalid_campaign_id`, `auto_send_not_configured`;\n404 `campaign_not_found`; 409 `integration_not_connected`; 422\n`campaign_unusable` or `provider_key_rejected`; 429\n`provider_rate_limited`; 502 `provider_unavailable`; 504\n`provider_timeout`.\n", "deprecated": false, "comingSoon": false, "params": [], "body": { "fields": [ { "name": "enabled", "type": "boolean", "required": true, "example": true, "description": "true arms auto-send, false disarms it and keeps the campaign.", "constraints": [] }, { "name": "provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "example": "smartlead", "description": "The tool to send to.", "constraints": [] }, { "name": "campaign_id", "type": "string", "required": false, "example": "42", "description": "A campaign in that tool that accepts leads. A JSON number is also accepted for Smartlead.", "constraints": [] } ], "example": { "enabled": true, "provider": "smartlead", "campaign_id": "42" } }, "response": { "code": "200", "description": "The updated setting.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "auto_send" ], "description": "", "constraints": [] }, { "name": "enabled", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead", null ], "description": "", "constraints": [] }, { "name": "campaign", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "campaign.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "campaign.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "selected_at", "type": "string | null", "required": false, "description": "When the campaign was chosen.", "constraints": [] }, { "name": "updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "auto_send", "enabled": true, "provider": "smartlead", "campaign": { "id": "42", "name": "Creator outreach Q4" }, "selected_at": "2026-10-07T10:00:00.000Z", "updated_at": "2026-10-07T10:00:00.000Z" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "422", "description": "The request is well formed but cannot be carried out: leads_not_eligible\n(a lead is unknown, locked under the plan, or has no email; nothing was\nsent), campaign_unusable (the campaign does not accept leads),\nprovider_key_rejected (reconnect the tool in the app), or\nprovider_payment_required (the vendor account needs a paid plan).\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "502", "description": "Instantly or Smartlead failed or timed out (502 provider_unavailable, 504 provider_timeout). Safe to retry after Retry-After." }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." }, { "code": "504", "description": "Instantly or Smartlead failed or timed out (502 provider_unavailable, 504 provider_timeout). Safe to retry after Retry-After." } ] }, { "id": "getOutreachIntegration", "method": "GET", "path": "/v1/integrations/{provider}", "group": "Outreach Integrations", "summary": "Retrieve an outreach integration", "description": "One integration's connection state. Any other method on this path\nanswers 405 `connect_in_app`: connect or disconnect the vendor key in\nthe app under Integrations.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "provider", "in": "path", "required": true, "type": "enum", "description": "The outreach tool. Anything else answers 404 integration_not_found.", "enum": [ "instantly", "smartlead" ], "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The integration.", "fields": [ { "name": "id", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "object", "type": "enum", "required": false, "enum": [ "integration" ], "description": "", "constraints": [] }, { "name": "provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "name", "type": "enum", "required": false, "enum": [ "Instantly", "Smartlead" ], "description": "", "constraints": [] }, { "name": "connected", "type": "boolean", "required": false, "description": "Whether the acting user has a vendor key connected in the app.", "constraints": [] }, { "name": "connected_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_validated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "last_used_campaign", "type": "object | null", "required": false, "description": "The campaign leads were last sent to from the app or the API.", "constraints": [] }, { "name": "last_used_campaign.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "last_used_campaign.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "last_used_campaign.status", "type": "enum", "required": false, "enum": [ "draft", "active", "paused", "completed", "running_subsequences", "accounts_unhealthy", "bounce_protect", "account_suspended", "stopped", "archived", "unknown" ], "description": "One vocabulary across vendors. Smartlead states outside this list are passed through lower-cased.", "constraints": [] }, { "name": "last_used_campaign.selected_at", "type": "string", "required": false, "description": "", "constraints": [] } ], "example": { "id": "instantly", "object": "integration", "provider": "instantly", "name": "Instantly", "connected": true, "connected_at": "2026-10-01T09:00:00.000Z", "last_validated_at": "2026-10-01T09:00:00.000Z", "last_used_campaign": { "id": "8c2f6a1e-4b7d-4f1a-9c3e-2d5b7a9e1f00", "name": "Summer UGC", "status": "active", "selected_at": "2026-10-03T12:00:00.000Z" } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "listOutreachCampaigns", "method": "GET", "path": "/v1/integrations/{provider}/campaigns", "group": "Outreach Integrations", "summary": "List campaigns", "description": "Campaigns in the user's connected Instantly or Smartlead account, read\nlive from the vendor. Only campaigns with `accepts_leads: true` can\nreceive leads (Instantly draft, active or paused; Smartlead active,\npaused or drafted), the same rule the app's campaign picker uses.\nInstantly pages in vendor order; Smartlead lists active campaigns\nfirst, then newest.\n\nErrors: 409 `integration_not_connected`, 422\n`provider_key_rejected`, 429 `provider_rate_limited`, 502\n`provider_unavailable`, 504 `provider_timeout`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "provider", "in": "path", "required": true, "type": "enum", "description": "The outreach tool. Anything else answers 404 integration_not_found.", "enum": [ "instantly", "smartlead" ], "constraints": [] }, { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 100, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] }, { "name": "search", "in": "query", "required": false, "type": "string", "description": "Filter by campaign name (Instantly searches on its side; Smartlead matches names case-insensitively).", "constraints": [ "max length 160" ] } ], "body": null, "response": { "code": "200", "description": "A page of campaigns.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.id", "type": "string", "required": false, "description": "Instantly UUID, or Smartlead numeric id as a string.", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "campaign" ], "description": "", "constraints": [] }, { "name": "data.provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "data.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "data.status", "type": "enum", "required": false, "enum": [ "draft", "active", "paused", "completed", "running_subsequences", "accounts_unhealthy", "bounce_protect", "account_suspended", "stopped", "archived", "unknown" ], "description": "One vocabulary across vendors. Smartlead states outside this list are passed through lower-cased.", "constraints": [] }, { "name": "data.provider_status", "type": "integer | string", "required": false, "description": "The raw vendor value: an Instantly number or a Smartlead upper-case word.", "constraints": [] }, { "name": "data.accepts_leads", "type": "boolean", "required": false, "description": "Whether leads can be sent to this campaign right now.", "constraints": [] }, { "name": "data.leads_sent", "type": "integer | null", "required": false, "description": "Instantly only: leads this user already sent to the campaign through UGC Agent.", "constraints": [] }, { "name": "data.lead_count", "type": "integer | null", "required": false, "description": "Smartlead only: total leads in the campaign as Smartlead reports it.", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "id": "8c2f6a1e-4b7d-4f1a-9c3e-2d5b7a9e1f00", "object": "campaign", "provider": "instantly", "name": "Summer UGC", "status": "active", "provider_status": 1, "accepts_leads": true, "leads_sent": 37, "lead_count": null } ] } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "422", "description": "The request is well formed but cannot be carried out: leads_not_eligible\n(a lead is unknown, locked under the plan, or has no email; nothing was\nsent), campaign_unusable (the campaign does not accept leads),\nprovider_key_rejected (reconnect the tool in the app), or\nprovider_payment_required (the vendor account needs a paid plan).\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "502", "description": "Instantly or Smartlead failed or timed out (502 provider_unavailable, 504 provider_timeout). Safe to retry after Retry-After." }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." }, { "code": "504", "description": "Instantly or Smartlead failed or timed out (502 provider_unavailable, 504 provider_timeout). Safe to retry after Retry-After." } ] }, { "id": "pushLeadsToCampaign", "method": "POST", "path": "/v1/integrations/{provider}/campaigns/{campaign_id}/leads", "group": "Outreach Integrations", "summary": "Send leads to a campaign", "description": "Adds creators you already have to an Instantly or Smartlead campaign,\nexactly like the app's \"Send to Instantly\" and \"Send to Smartlead\"\nactions: same eligibility, same personalization fields (`first_name`,\n`website`, and custom fields `creator_handle`, `creator_platform`,\n`creator_followers`, `creator_niche`, `creator_profile_url`; Smartlead\nalso gets `location`), and the same per-campaign tracking.\n\n`lead_ids` takes CRM lead ids from `GET /v1/leads` or the app's own\nlead ids. Without `chat_id` they are resolved against the user's Creator\nCRM (Saved Leads); with `chat_id` (from `GET /v1/chats`) against that\nchat's results. Every lead must be unlocked under the plan and have an\nemail, otherwise the whole request answers 422 `leads_not_eligible`\nand nothing is sent.\n\nRe-sending is safe: leads already sent to the campaign are skipped and\ncounted in `already_synced`. Send an `Idempotency-Key` to get the\nstored result back on a retry (`Idempotency-Replayed: true`) for 24\nhours; the same key with a different body answers 409\n`idempotency_conflict`. Smartlead imports in batches of 400; if a\nlater batch fails the response has `complete: false` and a `failure`,\nearlier batches stay imported, and repeating the request continues.\n\nErrors: 400 `invalid_lead_ids`, `duplicate_lead_ids`,\n`invalid_chat_id`, `invalid_campaign_id`; 404 `campaign_not_found`,\n`chat_not_found`, `integration_not_found`; 409\n`integration_not_connected`, `idempotency_conflict`; 422\n`leads_not_eligible`, `campaign_unusable`, `provider_key_rejected`,\n`provider_payment_required`; 429 `provider_rate_limited`; 502\n`provider_unavailable`; 503 `integrations_unavailable`; 504\n`provider_timeout`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "provider", "in": "path", "required": true, "type": "enum", "description": "The outreach tool. Anything else answers 404 integration_not_found.", "enum": [ "instantly", "smartlead" ], "constraints": [] }, { "name": "campaign_id", "in": "path", "required": true, "type": "string", "description": "Instantly campaign id (UUID), or Smartlead campaign id (a positive integer, sent as a string).", "constraints": [] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "lead_ids", "type": "string[]", "required": true, "example": [ "lead_3f9a1c0b7e2d4a5f6b8c9d0e" ], "description": "CRM lead ids from GET /v1/leads, or the app's own lead ids. No duplicates.", "constraints": [ "min 1 items", "max 1000 items" ] }, { "name": "chat_id", "type": "string", "required": false, "example": "conv_01H9Z2K4QW", "description": "Resolve lead_ids against this chat's results (an id from GET /v1/chats) instead of the Creator CRM.", "constraints": [ "max length 512" ] } ], "example": { "lead_ids": [ "lead_3f9a1c0b7e2d4a5f6b8c9d0e", "lead_7b1d2e3f4a5b6c7d8e9f0a1b" ] } }, "response": { "code": "200", "description": "What was sent.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "lead_push" ], "description": "", "constraints": [] }, { "name": "provider", "type": "enum", "required": false, "enum": [ "instantly", "smartlead" ], "description": "", "constraints": [] }, { "name": "campaign", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "campaign.id", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "campaign.name", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "campaign.status", "type": "enum", "required": false, "enum": [ "draft", "active", "paused", "completed", "running_subsequences", "accounts_unhealthy", "bounce_protect", "account_suspended", "stopped", "archived", "unknown" ], "description": "One vocabulary across vendors. Smartlead states outside this list are passed through lower-cased.", "constraints": [] }, { "name": "source", "type": "enum", "required": false, "enum": [ "saved_leads", "chat" ], "description": "Where lead_ids were resolved.", "constraints": [] }, { "name": "chat_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "requested", "type": "integer", "required": false, "description": "Leads in the request after resolving ids.", "constraints": [] }, { "name": "added", "type": "integer", "required": false, "description": "Leads newly added to the campaign.", "constraints": [] }, { "name": "already_synced", "type": "integer", "required": false, "description": "Leads skipped because UGC Agent already sent them to this campaign.", "constraints": [] }, { "name": "already_in_campaign", "type": "integer", "required": false, "description": "Leads the vendor reported as already in the campaign.", "constraints": [] }, { "name": "complete", "type": "boolean", "required": false, "description": "false when a Smartlead batch failed part way; repeat the request to continue.", "constraints": [] }, { "name": "tracking_complete", "type": "boolean", "required": false, "description": "Whether every sent lead was recorded for duplicate protection.", "constraints": [] }, { "name": "failure", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "failure.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "failure.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "details", "type": "object", "required": false, "description": "Vendor counters. Instantly: total_sent, uploaded, campaign_duplicates, workspace_duplicates, request_duplicates, blocklisted, invalid, skipped, remaining_quota, tracked_uploads. Smartlead: submitted, not_imported, tracked_uploads, batches_completed, batches_total.", "constraints": [] } ], "example": { "object": "lead_push", "provider": "instantly", "campaign": { "id": "8c2f6a1e-4b7d-4f1a-9c3e-2d5b7a9e1f00", "name": "Summer UGC", "status": "active" }, "source": "saved_leads", "chat_id": null, "requested": 3, "added": 2, "already_synced": 1, "already_in_campaign": 0, "complete": true, "tracking_complete": true, "failure": null, "details": { "total_sent": 2, "uploaded": 2, "campaign_duplicates": 0, "workspace_duplicates": 0, "request_duplicates": 0, "blocklisted": 0, "invalid": 0, "skipped": 0, "remaining_quota": null, "tracked_uploads": 2 } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "422", "description": "The request is well formed but cannot be carried out: leads_not_eligible\n(a lead is unknown, locked under the plan, or has no email; nothing was\nsent), campaign_unusable (the campaign does not accept leads),\nprovider_key_rejected (reconnect the tool in the app), or\nprovider_payment_required (the vendor account needs a paid plan).\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "502", "description": "Instantly or Smartlead failed or timed out (502 provider_unavailable, 504 provider_timeout). Safe to retry after Retry-After." }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." }, { "code": "504", "description": "Instantly or Smartlead failed or timed out (502 provider_unavailable, 504 provider_timeout). Safe to retry after Retry-After." } ] } ] }, { "name": "Workspace", "endpoints": [ { "id": "getPreferences", "method": "GET", "path": "/v1/preferences", "group": "Workspace", "summary": "Retrieve preferences", "description": "The Agent Preferences the web app's Agent Preferences screen edits:\nthe free-text creator criteria applied as defaults to every search\n(web app, API, MCP and automations), and whether creators without a\npublic email are accepted. A request's own constraints win when they\nconflict with a stored preference, but preferences can still narrow\nresults you did not expect to be narrowed; check them first when a\nsearch comes back short.\n\nPreferences belong to a person, not to the workspace. An API key acts\nas the team member who created it (the workspace owner for keys\ncreated before member attribution), so a key reads and writes its\ncreator's preferences. Changes show in the app immediately, and the other way\nround.\n", "deprecated": false, "comingSoon": false, "params": [], "body": null, "response": { "code": "200", "description": "The preferences.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "preferences" ], "description": "", "constraints": [] }, { "name": "agent_preferences", "type": "string", "required": false, "description": "Free-text default creator criteria applied to every search. Empty when none are set.", "constraints": [ "max length 2000" ] }, { "name": "accept_no_email_leads", "type": "boolean", "required": false, "description": "Whether creators without a public email are kept.", "constraints": [] }, { "name": "excluded_emails_count", "type": "integer", "required": false, "description": "How many creator emails are excluded from searches.", "constraints": [] }, { "name": "agent_preferences_updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "excluded_emails_updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "preferences", "agent_preferences": "Beauty and wellness creators, 5k-30k followers, UK or US, no agencies.", "accept_no_email_leads": false, "excluded_emails_count": 42, "agent_preferences_updated_at": "2026-10-07T10:12:00.000Z", "excluded_emails_updated_at": null } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "updatePreferences", "method": "PATCH", "path": "/v1/preferences", "group": "Workspace", "summary": "Update preferences", "description": "Changes the stored Agent Preferences. Send at least one field.\n`agent_preferences` is cleaned the way the app cleans it (trimmed,\ntrailing whitespace before newlines removed) and must be at most 2,000\ncharacters after cleaning; longer text is rejected with\n`preferences_too_long`, never truncated. `null` or an empty string\nclears it.\n\nSend an `Idempotency-Key` to replay the first response on a retry\n(`Idempotency-Replayed: true`); the same key with a different body\nanswers 409 `idempotency_conflict`.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "agent_preferences", "type": "string | null", "required": false, "example": "Beauty and wellness creators, 5k-30k followers, UK or US, no agencies.", "description": "Replaces the stored criteria. Limit applies after cleaning; null or \"\" clears.", "constraints": [ "max length 2000" ] }, { "name": "accept_no_email_leads", "type": "boolean", "required": false, "example": false, "description": "Keep creators without a public email.", "constraints": [] } ], "example": { "agent_preferences": "Beauty and wellness creators, 5k-30k followers, UK or US, no agencies.", "accept_no_email_leads": false } }, "response": { "code": "200", "description": "The updated preferences.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "preferences" ], "description": "", "constraints": [] }, { "name": "agent_preferences", "type": "string", "required": false, "description": "Free-text default creator criteria applied to every search. Empty when none are set.", "constraints": [ "max length 2000" ] }, { "name": "accept_no_email_leads", "type": "boolean", "required": false, "description": "Whether creators without a public email are kept.", "constraints": [] }, { "name": "excluded_emails_count", "type": "integer", "required": false, "description": "How many creator emails are excluded from searches.", "constraints": [] }, { "name": "agent_preferences_updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "excluded_emails_updated_at", "type": "string | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "listExcludedEmails", "method": "GET", "path": "/v1/preferences/excluded-emails", "group": "Workspace", "summary": "List excluded creators", "description": "Emails of creators excluded from every future search (the app's Agent\nPreferences, Manual exclusions): people you already work with from\nbefore UGC Agent. Sourcing never keeps a creator with one of these\nemails, in the app, the API, the MCP or automations. Creators UGC\nAgent already delivered to you are deduped automatically and do not\nneed to be listed here.\n\nSorted alphabetically. Emails are stored lowercased and deduplicated.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "limit", "in": "query", "required": false, "type": "integer", "description": "", "default": 100, "constraints": [ "min 1", "max 100" ] }, { "name": "cursor", "in": "query", "required": false, "type": "string", "description": "The next_cursor from the previous page.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "A page of excluded emails.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "list" ], "description": "", "constraints": [] }, { "name": "data", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "data.object", "type": "enum", "required": false, "enum": [ "excluded_email" ], "description": "", "constraints": [] }, { "name": "data.email", "type": "string", "required": false, "description": "Lowercased email address.", "constraints": [] }, { "name": "has_more", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "next_cursor", "type": "string | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "list", "data": [ { "object": "excluded_email", "email": "a@example.com" } ], "has_more": true, "next_cursor": "YUBleGFtcGxlLmNvbQ" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "addExcludedEmails", "method": "POST", "path": "/v1/preferences/excluded-emails", "group": "Workspace", "summary": "Exclude creators", "description": "Adds 1 to 2,000 emails per call. Each is trimmed, lowercased and must\nlook like an email address; one invalid entry rejects the whole call\nwith 400 `invalid_email` (param `emails[i]`) and nothing is written.\nA workspace member can hold at most 5,000 excluded emails; a call that\nwould pass that cap answers 409 `excluded_emails_limit_reached` and\nwrites nothing. Emails already excluded are reported in\n`already_excluded`.\n\nOptional `Idempotency-Key` replays the first response on a retry.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "emails", "type": "string[]", "required": true, "example": [ "jane@example.com" ], "description": "Email addresses. Trimmed and lowercased before saving.", "constraints": [ "min 1 items", "max 2000 items" ] } ], "example": { "emails": [ "Jane@Example.com", "ops@studio.example" ] } }, "response": { "code": "200", "description": "What changed.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "excluded_emails_change" ], "description": "", "constraints": [] }, { "name": "added", "type": "string[]", "required": false, "description": "POST only: emails newly excluded.", "constraints": [] }, { "name": "already_excluded", "type": "string[]", "required": false, "description": "POST only: emails that were already on the list.", "constraints": [] }, { "name": "removed", "type": "string[]", "required": false, "description": "DELETE only: emails taken off the list.", "constraints": [] }, { "name": "not_excluded", "type": "string[]", "required": false, "description": "DELETE only: emails that were not on the list.", "constraints": [] }, { "name": "excluded_emails_count", "type": "integer", "required": false, "description": "Total excluded emails after the change.", "constraints": [] } ], "example": { "object": "excluded_emails_change", "added": [ "jane@example.com" ], "already_excluded": [ "ops@studio.example" ], "excluded_emails_count": 43 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "removeExcludedEmails", "method": "DELETE", "path": "/v1/preferences/excluded-emails", "group": "Workspace", "summary": "Remove excluded creators", "description": "Removes 1 to 2,000 emails per call (same validation as adding), so\nthose creators can appear in searches again. Emails that were not on\nthe list are reported in `not_excluded`. Optional `Idempotency-Key`\nreplays the first response on a retry.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "emails", "type": "string[]", "required": true, "example": [ "jane@example.com" ], "description": "Email addresses. Trimmed and lowercased before saving.", "constraints": [ "min 1 items", "max 2000 items" ] } ], "example": { "emails": [ "jane@example.com", "x@example.com" ] } }, "response": { "code": "200", "description": "What changed.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "excluded_emails_change" ], "description": "", "constraints": [] }, { "name": "added", "type": "string[]", "required": false, "description": "POST only: emails newly excluded.", "constraints": [] }, { "name": "already_excluded", "type": "string[]", "required": false, "description": "POST only: emails that were already on the list.", "constraints": [] }, { "name": "removed", "type": "string[]", "required": false, "description": "DELETE only: emails taken off the list.", "constraints": [] }, { "name": "not_excluded", "type": "string[]", "required": false, "description": "DELETE only: emails that were not on the list.", "constraints": [] }, { "name": "excluded_emails_count", "type": "integer", "required": false, "description": "Total excluded emails after the change.", "constraints": [] } ], "example": { "object": "excluded_emails_change", "removed": [ "jane@example.com" ], "not_excluded": [ "x@example.com" ], "excluded_emails_count": 42 } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "removeExcludedEmail", "method": "DELETE", "path": "/v1/preferences/excluded-emails/{email}", "group": "Workspace", "summary": "Remove one excluded creator", "description": "Removes a single email from the exclusion list. No body. Answers 404\n`excluded_email_not_found` when the email is not on the list, and 400\n`invalid_email` when it does not look like an email address.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "email", "in": "path", "required": true, "type": "string", "description": "The excluded email, URL-encoded.", "constraints": [ "max length 320" ] }, { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": null, "response": { "code": "204", "description": "Removed.", "fields": [], "example": null }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] }, { "id": "getAccount", "method": "GET", "path": "/v1/account", "group": "Workspace", "summary": "Retrieve the account", "description": "What the app's plan badge and usage screens show: the plan, the\nmonthly lead pool, the API call quota windows and per-plan feature\nlimits. Read-only; it does not consume an API call. A `null` limit or\nremaining value means unlimited.\n\n`lead_pool` is the monthly new-lead pool. Team members report the\nteam owner's shared pool, with `via_team: true` and `team_id` set to\nthe owner. `api_calls` are the workspace's job-creating call windows,\nthe same numbers the X-Quota-* headers carry. `ugc_brands_access` is\n`none`, `overview` (Pro) or `full` (Premium and above).\n`enforced: false` only appears on a server without durable storage,\nwhere every limit reads as unlimited.\n", "deprecated": false, "comingSoon": false, "params": [], "body": null, "response": { "code": "200", "description": "The account summary.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "account" ], "description": "", "constraints": [] }, { "name": "workspace_id", "type": "string", "required": false, "description": "The workspace (team owner) the request acts for.", "constraints": [] }, { "name": "user_id", "type": "string", "required": false, "description": "The person acting: the hosted MCP user, or the team member who created the API key. Equals workspace_id for the owner.", "constraints": [] }, { "name": "role", "type": "enum", "required": false, "enum": [ "owner", "member" ], "description": "`member` when the acting person is a team member (their own API key or the hosted MCP).", "constraints": [] }, { "name": "plan", "type": "enum", "required": false, "enum": [ "premium", "ultra", "enterprise" ], "description": "The effective plan, team-inherited included. API keys are always ultra or enterprise; premium appears only for hosted MCP callers.", "constraints": [] }, { "name": "via_team", "type": "boolean", "required": false, "description": "True when the plan and lead pool are inherited from a team.", "constraints": [] }, { "name": "team_id", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "enforced", "type": "boolean", "required": false, "description": "False only on a server without durable storage; every limit then reads as unlimited.", "constraints": [] }, { "name": "lead_pool", "type": "object", "required": false, "description": "The monthly new-lead pool.", "constraints": [] }, { "name": "lead_pool.month", "type": "string", "required": false, "description": "YYYY-MM, UTC.", "constraints": [] }, { "name": "lead_pool.used", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "lead_pool.limit", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "lead_pool.remaining", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "visible_leads_limit", "type": "integer | null", "required": false, "description": "How many saved creators the plan can view; null means unlimited.", "constraints": [] }, { "name": "api_calls", "type": "object", "required": false, "description": "Job-creating API call windows. Reading them does not consume a call.", "constraints": [] }, { "name": "api_calls.daily", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "api_calls.daily.used", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "api_calls.daily.limit", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "api_calls.daily.remaining", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "api_calls.daily.resets_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "api_calls.monthly", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "api_calls.monthly.used", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "api_calls.monthly.limit", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "api_calls.monthly.remaining", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "api_calls.monthly.resets_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "limits", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "limits.max_automations", "type": "integer | null", "required": false, "description": "null means unlimited.", "constraints": [] }, { "name": "limits.tracked_creators", "type": "integer", "required": false, "description": "How many accounts Creator Tracking can follow on this plan.", "constraints": [] }, { "name": "ugc_brands_access", "type": "enum", "required": false, "enum": [ "none", "overview", "full" ], "description": "UGC Brands detail level: overview from Pro, full from Premium.", "constraints": [] } ], "example": { "object": "account", "workspace_id": "uid_owner", "user_id": "uid_owner", "role": "owner", "plan": "ultra", "via_team": false, "team_id": null, "enforced": true, "lead_pool": { "month": "2026-10", "used": 1200, "limit": null, "remaining": null }, "visible_leads_limit": null, "api_calls": { "daily": { "used": 3, "limit": 100, "remaining": 97, "resets_at": "2026-10-08T00:00:00.000Z" }, "monthly": { "used": 40, "limit": 2000, "remaining": 1960, "resets_at": "2026-11-01T00:00:00.000Z" } }, "limits": { "max_automations": null, "tracked_creators": 300 }, "ugc_brands_access": "full" } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "503", "description": "A dependency is temporarily unavailable. Retry after Retry-After seconds." } ] } ] }, { "name": "Research", "endpoints": [ { "id": "createCreatorAnalysis", "method": "POST", "path": "/v1/creator-analyses", "group": "Research", "summary": "Analyze a creator account", "description": "Analyzes one Instagram or TikTok account's recent posts with the same\nengine as the app's account analysis: views, likes, engagement,\nvirality, posting cadence, risk flags, and the top posts with the hook\neach one opens with.\n\nThe call waits a few seconds. A job that finishes in time answers 200\nwith the finished resource; otherwise it answers 202 with `Location`\nand `Retry-After`; poll GET /v1/creator-analyses/{id}. Send\n`background: true` to get the 202 straight away. A job that fails\nstill answers 200 (or shows on the poll) with `status: failed` and an\n`error` object (`creator_analysis_failed` or `credits_exhausted`).\n\nEach call consumes one job-creating call from the workspace quota\n(refunded on an idempotent replay or when the job could not be\ncreated). Credits are metered on pricing version `2026-08-01`: 5 for\nthe account fetch, 0 per post processed, 5 per transcribed video hook.\nNo leads are taken from the lead pool. Active jobs share the\nworkspace's active-job slots with creator searches (429\n`active_search_limit_reached` when full).\n\n`Idempotency-Key` is optional: the same key and body replays the job\nwith `Idempotency-Replayed: true`; a different body answers 409\n`idempotency_conflict`. Rate limits: 10 POSTs and 60 GETs per minute\n(buckets `creator_analysis:write` / `creator_analysis:read`).\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "handle", "type": "string", "required": true, "example": "skincarealex", "description": "Account handle. A leading @ is stripped and it is lowercased; no whitespace.", "constraints": [ "max length 100" ] }, { "name": "platform", "type": "enum", "required": false, "default": "instagram", "enum": [ "instagram", "tiktok" ], "example": "instagram", "description": "Where the account lives.", "constraints": [] }, { "name": "posts_per_creator", "type": "integer", "required": false, "default": 18, "example": 18, "description": "Recent posts to analyze.", "constraints": [ "min 1", "max 30" ] }, { "name": "top_videos", "type": "integer", "required": false, "default": 3, "example": 3, "description": "Top posts returned with their hooks.", "constraints": [ "min 1", "max 8" ] }, { "name": "analyze_video_hooks", "type": "boolean", "required": false, "default": true, "example": true, "description": "Transcribe the opening of each top video to read its hook (5 credits per hook).", "constraints": [] }, { "name": "background", "type": "boolean", "required": false, "default": false, "example": false, "description": "Answer 202 immediately instead of waiting.", "constraints": [] } ], "example": { "handle": "skincarealex", "platform": "instagram", "posts_per_creator": 18, "top_videos": 3, "analyze_video_hooks": true } }, "response": { "code": "200", "description": "The analysis finished (or failed) within the wait window.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_analysis" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "analysis", "type": "object | null", "required": false, "description": "The analysis once completed; null on failure.", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "partial_result", "type": "boolean", "required": false, "description": "Failed jobs only; always false today.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "creator_analysis", "id": "job_01J9ANALYSIS", "status": "completed", "created_at": "2026-10-07T10:00:00.000Z", "completed_at": "2026-10-07T10:00:09.000Z", "handle": "skincarealex", "platform": "instagram", "analysis": { "handle": "skincarealex", "platform": "instagram", "display_name": "Alex Skin", "followers": 12000, "bio": "Skincare creator", "profile_url": "https://www.instagram.com/skincarealex/", "posts_analyzed": 18, "videos_analyzed": 8, "median_views": 3000, "max_views": 20000, "avg_likes": 400, "viral_score_version": 2, "max_likes": 1500, "median_likes": 300, "viral_post_count": 2, "consistency_score": 0.7, "breakout_score": 0.4, "engagement_rate": 0.08, "viral_score": 0.9, "post_cadence_days": 2.5, "top_posts": [ { "url": "https://www.instagram.com/reel/C9xyz/", "views": 20000, "likes": 1500, "impact_multiplier": 6.7, "caption": "my 3 step night routine", "posted_at": 1727000000000, "hook": "nobody talks about this", "hook_source": "video", "hook_style": "contrarian" } ], "format_notes": [ "Talking-head reels outperform carousels." ], "risk_flags": [], "fetched_at": 1727000000000 }, "usage": { "pricing_version": "2026-08-01", "credits_consumed": 10, "breakdown": [ { "feature": "creator_analysis", "meter": "creator_analysis.account_fetch", "quantity": 1, "unit_cost": 5, "credits": 5 }, { "feature": "creator_analysis", "meter": "creator_analysis.video_hook", "quantity": 1, "unit_cost": 5, "credits": 5 } ] } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." } ] }, { "id": "getCreatorAnalysis", "method": "GET", "path": "/v1/creator-analyses/{id}", "group": "Research", "summary": "Retrieve a creator analysis", "description": "The analysis in its current state. `status` moves queued -> running ->\ncompleted | failed. Unknown ids and other workspaces' jobs answer 404\n`creator_analysis_not_found`. Results are kept for 30 days.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "The job id returned by POST /v1/creator-analyses.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The analysis.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_analysis" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "analysis", "type": "object | null", "required": false, "description": "The analysis once completed; null on failure.", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "partial_result", "type": "boolean", "required": false, "description": "Failed jobs only; always false today.", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "createCreatorEnrichment", "method": "POST", "path": "/v1/creator-enrichments", "group": "Research", "summary": "Enrich creators", "description": "Looks up 1 to 50 specific creators by handle or profile URL and\nreturns each one's profile, follower count, bio, public email and fit\nscore, using the same sources, email recovery, qualification and\ncreator index as the app. Add `qualification_prompt` to check each\ncreator against a brief.\n\nEach entry in `creators` is either `{platform, handle}` (handle 2 to\n30 letters, digits, dots or underscores; a leading @ is stripped) or\n`{url}` (a canonical Instagram or TikTok profile URL). Duplicates\nafter normalization answer 400 `duplicate_creator`. Every input gets\none row in `results`, with `status` enriched, not_found or failed.\n\nSame async pattern as creator analyses: 200 when finished within the\nwait window, else 202 with `Location` and `Retry-After`;\n`background: true` answers 202 at once. Failed jobs carry\n`error.code` `creator_enrichment_failed` or `credits_exhausted`.\n\nEach call consumes one job-creating call (refunded on replay or when\nno job was created). Credits are metered on pricing version\n`2026-08-20`: 1 per index hit, 2 per live profile fetch, 2 per\nrecovered email, 1 per qualification. No leads are taken from the\nlead pool. Profile pictures are durable media-cache URLs.\n`Idempotency-Key` is optional. Rate limits: 10 POSTs and 60 GETs per\nminute.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "creators", "type": "object[]", "required": true, "description": "Creators to look up. Duplicates are rejected.", "constraints": [ "min 1 items", "max 50 items" ] }, { "name": "creators.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "example": "instagram", "description": "Required with handle; must agree with url when both are sent.", "constraints": [] }, { "name": "creators.handle", "type": "string", "required": false, "example": "anna.ugc", "description": "2 to 30 letters, digits, dots or underscores.", "constraints": [] }, { "name": "creators.url", "type": "string", "required": false, "example": "https://www.instagram.com/anna.ugc/", "description": "A canonical Instagram or TikTok profile URL.", "constraints": [] }, { "name": "recover_emails", "type": "boolean", "required": false, "default": true, "example": true, "description": "Run public email recovery when no email is on the profile.", "constraints": [] }, { "name": "qualification_prompt", "type": "string | null", "required": false, "example": "UGC creators who film skincare routines", "description": "A brief to check each creator against.", "constraints": [ "min length 3", "max length 5000" ] }, { "name": "background", "type": "boolean", "required": false, "default": false, "example": false, "description": "Answer 202 immediately instead of waiting.", "constraints": [] } ], "example": { "creators": [ { "platform": "instagram", "handle": "anna.ugc" }, { "url": "https://www.tiktok.com/@maya.makes" } ], "recover_emails": true, "qualification_prompt": "UGC creators who film skincare routines" } }, "response": { "code": "200", "description": "The enrichment finished (or failed) within the wait window.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_enrichment" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "input_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "counts.requested", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts.enriched", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts.not_found", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts.failed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "results", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "results.input_index", "type": "integer", "required": false, "description": "Position in the request creators array.", "constraints": [] }, { "name": "results.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "results.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "results.status", "type": "enum", "required": false, "enum": [ "enriched", "not_found", "failed" ], "description": "", "constraints": [] }, { "name": "results.source", "type": "enum", "required": false, "enum": [ "index", "live", null ], "description": "index: the shared creator index; live: fetched fresh.", "constraints": [] }, { "name": "results.creator", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "results.qualification", "type": "object | null", "required": false, "description": "Only when qualification_prompt was sent.", "constraints": [] }, { "name": "results.qualification.matched", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "results.qualification.evidence", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "results.error", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "results.error.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "results.error.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "creator_enrichment", "id": "job_01J9ENRICH", "status": "completed", "created_at": "2026-10-07T10:00:00.000Z", "completed_at": "2026-10-07T10:00:07.000Z", "input_count": 2, "counts": { "requested": 2, "enriched": 1, "not_found": 1, "failed": 0 }, "results": [ { "input_index": 0, "platform": "instagram", "handle": "anna.ugc", "status": "enriched", "source": "index", "creator": { "platform": "instagram", "handle": "anna.ugc", "name": "Anna", "first_name": "Anna", "profile_url": "https://www.instagram.com/anna.ugc/", "profile_picture_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fscontent.cdninstagram.com%2Fa.jpg&h=anna.ugc", "followers": 4200, "bio": "UGC creator", "skincare and wellness": null, "email": "anna@example.com", "email_type": "personal", "email_source": "bio", "email_status": "valid", "links": [ "https://anna.example.com" ], "is_private": false, "media_count": 120, "score": 82, "score_reasons": [ "Posts UGC-style product videos" ] }, "qualification": { "matched": true, "evidence": [ "Films morning and night skincare routines" ] }, "error": null }, { "input_index": 1, "platform": "tiktok", "handle": "maya.makes", "status": "not_found", "source": null, "creator": null, "qualification": null, "error": { "code": "creator_not_found", "message": "Creator not found." } } ], "usage": { "pricing_version": "2026-08-20", "credits_consumed": 2, "breakdown": [ { "feature": "creator_enrichment", "meter": "creator_enrichment.index_hit", "quantity": 1, "unit_cost": 1, "credits": 1 }, { "feature": "creator_enrichment", "meter": "creator_enrichment.qualification", "quantity": 1, "unit_cost": 1, "credits": 1 } ] } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." } ] }, { "id": "getCreatorEnrichment", "method": "GET", "path": "/v1/creator-enrichments/{id}", "group": "Research", "summary": "Retrieve a creator enrichment", "description": "The enrichment in its current state. Unknown ids and other\nworkspaces' jobs answer 404 `creator_enrichment_not_found`. Results\nare kept for 30 days.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "The job id returned by POST /v1/creator-enrichments.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The enrichment.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "creator_enrichment" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "input_count", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "counts.requested", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts.enriched", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts.not_found", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "counts.failed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "results", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "results.input_index", "type": "integer", "required": false, "description": "Position in the request creators array.", "constraints": [] }, { "name": "results.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "results.handle", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "results.status", "type": "enum", "required": false, "enum": [ "enriched", "not_found", "failed" ], "description": "", "constraints": [] }, { "name": "results.source", "type": "enum", "required": false, "enum": [ "index", "live", null ], "description": "index: the shared creator index; live: fetched fresh.", "constraints": [] }, { "name": "results.creator", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "results.qualification", "type": "object | null", "required": false, "description": "Only when qualification_prompt was sent.", "constraints": [] }, { "name": "results.qualification.matched", "type": "boolean", "required": false, "description": "", "constraints": [] }, { "name": "results.qualification.evidence", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "results.error", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "results.error.code", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "results.error.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "createBrandResearch", "method": "POST", "path": "/v1/brand-researches", "group": "Research", "summary": "Research a brand's creators", "description": "Finds creators who already made public content for one brand and\nverifies each video: evidence level (`confirmed_partnership`,\n`strong_ugc`, `possible_organic`), sponsorship, affiliate and gifting\ndisclosures, and the brand's official domains and profiles. Name one\nbrand or product in `prompt` (a quoted name, a domain, or \"creators\nwho worked with X\"); a prompt that does not identify one brand fails\nwith `ambiguous_brand`.\n\nUse it for any brand. For brands already in the curated dataset, the\nUGC Brands endpoints (`/v1/ugc-brands`) answer instantly.\n\nWhile it runs, `progress` reports the phase (queued,\nidentifying_brand, discovering, verifying, aggregating) and running\ncounts. Same async pattern as the other research jobs: 200 when\nfinished within the wait window, else 202 with `Location` and\n`Retry-After`. Terminal failures carry `error.code`\n`brand_research_failed`, `ambiguous_brand` or `credits_exhausted`.\n\nEach call consumes one job-creating call (refunded on replay or when\nno job was created). Credits are metered on pricing version\n`2026-08-21`: 5 per creator included in the report, 0 per verified\nvideo. No leads are taken from the lead pool. Avatars and logos are\ndurable media-cache URLs. `Idempotency-Key` is optional. Rate limits:\n10 POSTs and 60 GETs per minute.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "prompt", "type": "string", "required": true, "example": "Find creators who worked with Cal AI", "description": "Names one brand or product.", "constraints": [ "min length 3", "max length 5000" ] }, { "name": "platforms", "type": "enum[]", "required": false, "enum": [ "instagram", "tiktok" ], "example": [ "instagram", "tiktok" ], "description": "Unique values. Omit for both.", "constraints": [] }, { "name": "max_creators", "type": "integer", "required": false, "default": 200, "example": 50, "description": "Most creators to include in the report.", "constraints": [ "min 1", "max 200" ] }, { "name": "include_possible_organic", "type": "boolean", "required": false, "default": true, "example": false, "description": "Also include creators whose posts mention the brand without a clear partnership.", "constraints": [] }, { "name": "background", "type": "boolean", "required": false, "default": false, "example": true, "description": "Answer 202 immediately instead of waiting.", "constraints": [] } ], "example": { "prompt": "Find creators who worked with Cal AI", "platforms": [ "instagram", "tiktok" ], "max_creators": 50, "include_possible_organic": false, "background": true } }, "response": { "code": "200", "description": "The research finished (or failed) within the wait window.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "brand_research" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "progress.phase", "type": "enum", "required": false, "enum": [ "queued", "identifying_brand", "discovering", "verifying", "aggregating", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "progress.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "progress.completed_units", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.total_units", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "progress.candidate_videos_discovered", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.videos_verified", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.creators_included", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "brand", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "result", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." } ] }, { "id": "getBrandResearch", "method": "GET", "path": "/v1/brand-researches/{id}", "group": "Research", "summary": "Retrieve a brand research", "description": "The research in its current state, with `progress` while it runs and\n`brand` plus `result` once completed. A malformed id answers 400\n`invalid_resource_id`; unknown ids and other workspaces' jobs answer\n404 `brand_research_not_found`. Results are kept for 30 days.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "The job id returned by POST /v1/brand-researches.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The research.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "brand_research" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "description": "", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "prompt", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "progress", "type": "object", "required": false, "description": "", "constraints": [] }, { "name": "progress.phase", "type": "enum", "required": false, "enum": [ "queued", "identifying_brand", "discovering", "verifying", "aggregating", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "progress.message", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "progress.completed_units", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.total_units", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "progress.candidate_videos_discovered", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.videos_verified", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.creators_included", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "progress.updated_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "brand", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "result", "type": "object | null", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "brand_research", "id": "job_01J9BRAND", "status": "completed", "created_at": "2026-10-07T10:00:00.000Z", "completed_at": "2026-10-07T10:04:10.000Z", "prompt": "Find creators who worked with Cal AI", "progress": { "phase": "completed", "message": "Report complete.", "completed_units": 4, "total_units": 4, "candidate_videos_discovered": 140, "videos_verified": 60, "creators_included": 22, "updated_at": "2026-10-07T10:04:10.000Z" }, "brand": { "query": "Cal AI", "canonical_name": "cal ai", "display_name": "Cal AI", "aliases": [], "official_domains": [ "calai.app" ], "official_profiles": [ { "platform": "instagram", "url": "https://www.instagram.com/cal.ai/", "label": null } ], "description": "AI calorie tracker", "slogan": null, "logo_url": null, "industries": [ "health" ], "confidence": 0.94, "verification_explanation": "Official domain and profiles match." }, "result": { "creators": [ { "platform": "tiktok", "handle": "maya", "profile_url": "https://www.tiktok.com/@maya", "display_name": "Maya", "avatar_url": "https://app.ugcagent.app/api/avatar?url=https%3A%2F%2Fp16.tiktokcdn.com%2Fa.jpg&h=maya", "bio_excerpt": "fitness and food", "follower_count": 8200, "strongest_evidence_level": "confirmed_partnership", "qualifying_video_count": 2, "first_qualifying_at": "2026-08-02T12:00:00.000Z", "latest_qualifying_at": "2026-09-20T12:00:00.000Z", "content_formats": [ "video" ], "qualifying_videos": [ { "platform": "tiktok", "canonical_post_id": "7412345678901234567", "canonical_video_url": "https://www.tiktok.com/@maya/video/7412345678901234567", "creator_handle": "maya", "creator_profile_url": "https://www.tiktok.com/@maya", "caption_excerpt": "tracking my meals with @calai #ad", "published_at": "2026-09-20T12:00:00.000Z", "evidence_level": "confirmed_partnership", "confidence": 0.9, "verification_explanation": "Disclosed paid partnership naming the brand.", "disclosure": { "sponsorship": "explicit", "affiliate": "not_observed", "gifted": "not_observed", "paid_partnership_label_observed": true, "evidence": [ "#ad" ] } } ] } ], "coverage": { "meaning": "publicly_discoverable_coverage", "requested_platforms": [ "instagram", "tiktok" ], "searched_platforms": [ "instagram", "tiktok" ], "candidate_videos_discovered": 140, "videos_verified": 60, "qualifying_videos": 30, "creators_included": 22, "possible_organic_creators": 4, "rejected_videos": 30, "limitations": [], "completed_at": "2026-10-07T10:04:10.000Z" }, "default_visible_evidence_levels": [ "confirmed_partnership", "strong_ugc" ], "possible_organic_available": true, "generated_at": "2026-10-07T10:04:10.000Z" }, "usage": { "pricing_version": "2026-08-21", "credits_consumed": 110, "breakdown": [ { "feature": "brand_research", "meter": "brand_research.creator_included", "quantity": 22, "unit_cost": 5, "credits": 110 }, { "feature": "brand_research", "meter": "brand_research.video_verified", "quantity": 60, "unit_cost": 0, "credits": 0 } ] } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] }, { "id": "createTrendResearch", "method": "POST", "path": "/v1/trend-researches", "group": "Research", "summary": "Research current trends", "description": "Researches what is trending right now for a topic on TikTok,\nInstagram or both, exactly like the app chat's latest-trends research:\nit collects direct proof posts, cites web sources, and writes up only\nthe trends it can verify against that evidence (often one or two, at\nleast one per requested platform that has proof). Each trend says\nwhat the evidence shows and how to use it in a UGC video; evidence ids\n`S` point at `direct_proof_posts`, `W` at `cited_web_sources`.\n\nResearch usually takes 20 to 60 seconds, so expect 202 with\n`Location` and a `Retry-After` of at least 5 seconds; or send\n`background: true` and poll GET /v1/trend-researches/{id}. A job has\n10 minutes before it fails with `trend_research_timeout`; other\nfailures carry `trend_research_failed`.\n\nPriced like the app: each call consumes one job-creating call\n(refunded on replay or when no job was created) and settles 0 credits\non pricing version `2026-10-07` (meter `trend_research.report`). No\nleads are taken from the lead pool. `Idempotency-Key` is optional.\nQuery parameters are rejected (`unknown_parameter`). Rate limits: 10\nPOSTs and 60 GETs per minute.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "Idempotency-Key", "in": "header", "required": false, "type": "string", "description": "Makes the request safe to retry. Required on POST /v1/creator-searches.\nThe same key with the same body replays the stored result (with\nIdempotency-Replayed: true) for 24 hours; a different body answers 409\nidempotency_conflict. A duplicate sent while the first request is still\nrunning answers 409 idempotency_in_progress with Retry-After. Only\nsuccesses and 400/422 validation errors are stored against the key; \n5xx, 402, 404, 409 or 429 releases it so the retry can run.\n", "constraints": [ "max length 255" ] } ], "body": { "fields": [ { "name": "topic", "type": "string", "required": true, "example": "skincare", "description": "Niche, product category or topic. Whitespace is collapsed.", "constraints": [ "min length 2", "max length 200" ] }, { "name": "platform", "type": "enum", "required": false, "default": "both", "enum": [ "tiktok", "instagram", "both" ], "example": "both", "description": "Where to look.", "constraints": [] }, { "name": "region", "type": "string", "required": false, "default": "Global", "example": "UK", "description": "Audience region or country.", "constraints": [ "min length 2", "max length 100" ] }, { "name": "max_posts", "type": "integer", "required": false, "default": 12, "example": 12, "description": "Direct proof posts the evidence pass collects.", "constraints": [ "min 3", "max 30" ] }, { "name": "background", "type": "boolean", "required": false, "default": false, "example": true, "description": "Answer 202 immediately instead of waiting.", "constraints": [] } ], "example": { "topic": "skincare", "platform": "both", "region": "UK", "max_posts": 12, "background": true } }, "response": { "code": "200", "description": "The research finished (or failed) within the wait window.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "trend_research" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "both" ], "description": "", "constraints": [] }, { "name": "region", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "researched_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "evidence_mode", "type": "enum", "required": false, "enum": [ "social", "web", "none" ], "description": "social: proof posts found; web: only cited web sources; none: nothing current.", "constraints": [] }, { "name": "social_retrieval_status", "type": "enum", "required": false, "enum": [ "complete", "partial", "empty", "unavailable" ], "description": "", "constraints": [] }, { "name": "synthesis_status", "type": "enum", "required": false, "enum": [ "succeeded", "no_evidence", "unavailable" ], "description": "succeeded: trends written and verified. no_evidence: nothing current could be verified, trends is empty. unavailable: the write-up failed validation, trends is empty but proof posts and sources are returned.", "constraints": [] }, { "name": "trends", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "trends.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "web" ], "description": "web: a web-grounded signal cited only to W sources.", "constraints": [] }, { "name": "trends.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "trends.observation", "type": "string", "required": false, "description": "What the evidence shows.", "constraints": [] }, { "name": "trends.how_to_use", "type": "string", "required": false, "description": "How to apply it in a UGC video.", "constraints": [] }, { "name": "trends.evidence", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "trends.evidence.id", "type": "string", "required": false, "description": "S for a proof post, W for a web source.", "constraints": [] }, { "name": "trends.evidence.kind", "type": "enum", "required": false, "enum": [ "social", "web" ], "description": "", "constraints": [] }, { "name": "trends.evidence.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", null ], "description": "", "constraints": [] }, { "name": "trends.evidence.url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "trends.evidence.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.id", "type": "string", "required": false, "description": "S.", "constraints": [] }, { "name": "direct_proof_posts.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "direct_proof_posts.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.author", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.caption", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.hook", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.sound", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.comments", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.shares", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.source", "type": "enum", "required": false, "enum": [ "platform_api", "web_index", null ], "description": "web_index: found through a web index because the platform returned nothing.", "constraints": [] }, { "name": "cited_web_sources", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "cited_web_sources.id", "type": "string", "required": false, "description": "W.", "constraints": [] }, { "name": "cited_web_sources.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "cited_web_sources.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "web_claims", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "web_claims.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "web_claims.source_ids", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ] }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "403", "description": "The key is valid but the workspace plan does not include API access." }, { "code": "409", "description": "The request conflicts with existing state: an Idempotency-Key reused\nwith a different body (idempotency_conflict), a duplicate sent while\nthe first request with that key is still running\n(idempotency_in_progress, with Retry-After), a workspace limit\n(list_limit_reached, webhook_limit_reached), or an active run.\n" }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" }, { "code": "500", "description": "Something failed server-side. The turn is safe to send again." } ] }, { "id": "getTrendResearch", "method": "GET", "path": "/v1/trend-researches/{id}", "group": "Research", "summary": "Retrieve a trend research", "description": "The research in its current state; the trends, proof posts and web\nsources appear once `status` is completed. No query parameters are\naccepted. A malformed id answers 400 `invalid_id`; unknown ids and\nother workspaces' jobs answer 404 `trend_research_not_found`. Results\nare kept for 30 days.\n", "deprecated": false, "comingSoon": false, "params": [ { "name": "id", "in": "path", "required": true, "type": "string", "description": "The job id returned by POST /v1/trend-researches.", "constraints": [] } ], "body": null, "response": { "code": "200", "description": "The research.", "fields": [ { "name": "object", "type": "enum", "required": false, "enum": [ "trend_research" ], "description": "", "constraints": [] }, { "name": "id", "type": "string", "required": false, "description": "Job id, prefixed job_.", "constraints": [] }, { "name": "created_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "topic", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "both" ], "description": "", "constraints": [] }, { "name": "region", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "status", "type": "enum", "required": false, "enum": [ "queued", "running", "completed", "failed" ], "description": "", "constraints": [] }, { "name": "completed_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "researched_at", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "evidence_mode", "type": "enum", "required": false, "enum": [ "social", "web", "none" ], "description": "social: proof posts found; web: only cited web sources; none: nothing current.", "constraints": [] }, { "name": "social_retrieval_status", "type": "enum", "required": false, "enum": [ "complete", "partial", "empty", "unavailable" ], "description": "", "constraints": [] }, { "name": "synthesis_status", "type": "enum", "required": false, "enum": [ "succeeded", "no_evidence", "unavailable" ], "description": "succeeded: trends written and verified. no_evidence: nothing current could be verified, trends is empty. unavailable: the write-up failed validation, trends is empty but proof posts and sources are returned.", "constraints": [] }, { "name": "trends", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "trends.platform", "type": "enum", "required": false, "enum": [ "tiktok", "instagram", "web" ], "description": "web: a web-grounded signal cited only to W sources.", "constraints": [] }, { "name": "trends.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "trends.observation", "type": "string", "required": false, "description": "What the evidence shows.", "constraints": [] }, { "name": "trends.how_to_use", "type": "string", "required": false, "description": "How to apply it in a UGC video.", "constraints": [] }, { "name": "trends.evidence", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "trends.evidence.id", "type": "string", "required": false, "description": "S for a proof post, W for a web source.", "constraints": [] }, { "name": "trends.evidence.kind", "type": "enum", "required": false, "enum": [ "social", "web" ], "description": "", "constraints": [] }, { "name": "trends.evidence.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok", null ], "description": "", "constraints": [] }, { "name": "trends.evidence.url", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "trends.evidence.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.id", "type": "string", "required": false, "description": "S.", "constraints": [] }, { "name": "direct_proof_posts.platform", "type": "enum", "required": false, "enum": [ "instagram", "tiktok" ], "description": "", "constraints": [] }, { "name": "direct_proof_posts.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.author", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.caption", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.hook", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.sound", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.hashtags", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.views", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.likes", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.comments", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.shares", "type": "integer | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.posted_at", "type": "string | null", "required": false, "description": "", "constraints": [] }, { "name": "direct_proof_posts.source", "type": "enum", "required": false, "enum": [ "platform_api", "web_index", null ], "description": "web_index: found through a web index because the platform returned nothing.", "constraints": [] }, { "name": "cited_web_sources", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "cited_web_sources.id", "type": "string", "required": false, "description": "W.", "constraints": [] }, { "name": "cited_web_sources.title", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "cited_web_sources.url", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "web_claims", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "web_claims.text", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "web_claims.source_ids", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "notes", "type": "string[]", "required": false, "description": "", "constraints": [] }, { "name": "usage", "type": "object", "required": false, "description": "Credits metered for the job. Ultra and Enterprise have no monthly credit ceiling, so this is reporting, not a limit.", "constraints": [] }, { "name": "usage.pricing_version", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.credits_consumed", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown", "type": "object[]", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.feature", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.meter", "type": "string", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.quantity", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.unit_cost", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "usage.breakdown.credits", "type": "integer", "required": false, "description": "", "constraints": [] }, { "name": "error", "type": "object | null", "required": false, "description": "", "constraints": [] } ], "example": { "object": "trend_research", "id": "job_01J9TREND", "created_at": "2026-10-07T10:00:00.000Z", "topic": "skincare", "platform": "both", "region": "UK", "status": "completed", "completed_at": "2026-10-07T10:00:41.000Z", "researched_at": "2026-10-07T10:00:30.000Z", "evidence_mode": "social", "social_retrieval_status": "complete", "synthesis_status": "succeeded", "trends": [ { "platform": "tiktok", "title": "Shelfie night routines", "observation": "Creators film their shelf before bed and name each step.", "how_to_use": "Open on the shelf, then the product in hand.", "evidence": [ { "id": "S1", "kind": "social", "platform": "tiktok", "url": "https://www.tiktok.com/@maya/video/1", "title": "TikTok @maya" } ] } ], "direct_proof_posts": [ { "id": "S1", "platform": "tiktok", "url": "https://www.tiktok.com/@maya/video/1", "author": "maya", "caption": "night routine", "hook": "my shelf", "sound": "original sound", "hashtags": [ "#skincare" ], "views": 120000, "likes": 9000, "comments": 120, "shares": 40, "posted_at": "2026-10-05T09:00:00.000Z", "source": "platform_api" } ], "cited_web_sources": [ { "id": "W1", "title": "Trend report", "url": "https://example.com/report" } ], "web_claims": [ { "text": "Night routines are up", "source_ids": [ "W1" ] } ], "notes": [ "Ranked by available views and engagement with a recency boost." ], "usage": { "pricing_version": "2026-10-07", "credits_consumed": 0, "breakdown": [ { "feature": "trend_research", "meter": "trend_research.report", "quantity": 1, "unit_cost": 0, "credits": 0 } ] } } }, "errors": [ { "code": "400", "description": "A field failed validation." }, { "code": "401", "description": "Missing, malformed, or revoked API key." }, { "code": "404", "description": "No resource with that id belongs to this workspace." }, { "code": "429", "description": "Too many requests. Back off and honour Retry-After. error.code is\napi_rate_limit_exceeded for the per-minute limiter, or\napi_daily_quota_exceeded / api_monthly_quota_exceeded when an Ultr\nworkspace has used its 100 calls per UTC day or 2,000 per month\n(Enterprise has no call caps).\n" } ] } ] } ], "count": 111, "liveCount": 111, "generatedFrom": "assets/openapi.yaml" }