Submit Instagram handles to this endpoint.
source_query field is optional. It is a free-text note for your own attribution — for example the search that surfaced this creator — and does not affect processing.
Responses
A new ingest returns202 Accepted:
200 OK with status: "already_exists" and the same shape, at no charge.
Polling for the Profile
The profile builds asynchronously. Poll the returnedstatus_url (which is GET /v1/creators/{id}) to retrieve it:
- Profile fields and creator analysis become available at different times; inspect the timestamps below.
- While the profile is building,
GET /v1/creators/{id}can return404or sparse fields. Apply an attempt limit and a deadline; do not poll indefinitely.
Poll with a budget
After a successful ingest, pass its returneddata.status_url to this helper. It makes at most five reads, waits at least a minute between them, honors Retry-After, and stops at ten minutes. A populated data_updated_at on an expanded profile is this example’s readiness criterion; it does not mean full creator analysis has finished.
poll-profile.ts
await waitForProfile(ingestResponse.data.status_url) using the response from your ingest request. This bounds successful lookup charges to 0.5 credits ($0.005), in addition to the 5-credit ($0.05) new-ingest charge. Sparse successful reads are still lookups. The deadline is a job budget, not a promised completion time; full analysis can take longer.
Stop on a failed ingest 404 and check the handle. The helper’s temporary 404 handling applies only after an accepted ingest. Preserve partial fields and freshness timestamps while showing a processing state.
Billing
Ingest costs 5 credits ($0.05) when the API accepts a new creator for enrichment (202). You are not charged when:
- the creator already exists (
200 already_exists), - the handle does not exist (
404), - the handle format is invalid (
422), - or you exceed the daily quota (
429).
Limits
Each account has a daily ingest quota (default 50 per UTC day). Exceeding it returns429 with error.code: "quota_exceeded" and a Retry-After header pointing to the next UTC midnight:
202 path). Handles that do not exist (404) or cannot be validated right now (503) do not use a slot. A later retry accepted as a new ingest consumes one quota slot and is billed normally.
If you need a higher quota, reach out at elliot@influship.com.