Skip to main content
Add a public Instagram creator by handle, then retrieve their profile as enrichment progresses. Use this when profile lookup does not find a creator you want to research. Submit Instagram handles to this endpoint.
The 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 returns 202 Accepted:
For an existing creator, the API returns 200 OK with status: "already_exists" and the same shape, at no charge.

Polling for the Profile

The profile builds asynchronously. Poll the returned status_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 return 404 or sparse fields. Apply an attempt limit and a deadline; do not poll indefinitely.

Poll with a budget

After a successful ingest, pass its returned data.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
Call 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 returns 429 with error.code: "quota_exceeded" and a Retry-After header pointing to the next UTC midnight:
The quota is only consumed when a request is accepted (the 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.

Error Reference