> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest Creators On Demand

> Request ingestion of a creator we do not have yet, then poll for the built profile.

# Ingest Creators On Demand

Most creators you search for are already in Influship. When one is not, use `POST /v1/creators/ingest` to request it. We validate the handle live to confirm it exists, seed a profile, and start building it in the background. You then poll for the result.

Only Instagram is supported today.

```bash theme={null}
curl -s "https://api.influship.com/v1/creators/ingest" \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "username": "fitness_coach_jane",
    "source_query": "vegan fitness coaches in Austin"
  }'
```

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`:

```json theme={null}
{
  "data": {
    "status": "ingesting",
    "creator": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "fitness_coach_jane",
      "platform": "instagram"
    },
    "status_url": "/v1/creators/123e4567-e89b-12d3-a456-426614174000"
  }
}
```

If we already have the creator, you get `200 OK` with `status: "already_exists"` and the same shape. This path is **not charged**.

## Polling for the Profile

The profile builds asynchronously. Poll the returned `status_url` (which is `GET /v1/creators/{id}`) to retrieve it:

* Basic header details (name, bio) are usually available within about a minute.
* Full analysis and synthesized fields fill in within about a day.
* While the profile is still building, `GET /v1/creators/{id}` may return `404` or sparse fields. Keep polling with a sensible backoff — every few minutes is plenty.

```bash theme={null}
curl -s "https://api.influship.com/v1/creators/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: $INFLUSHIP_API_KEY"
```

## Billing

Ingest costs **5 credits (\$0.05)**, charged only when a new creator is seeded (the `202` path). 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:

```json theme={null}
{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily ingest quota of 50 exceeded. Try again after it resets at UTC midnight."
  }
}
```

If you need a higher quota, reach out at [elliot@influship.com](mailto:elliot@influship.com).

## Error Reference

| Status | Meaning                                                 | Charged |
| ------ | ------------------------------------------------------- | ------- |
| `202`  | New creator seeded; enrichment started                  | Yes     |
| `200`  | Creator already exists                                  | No      |
| `400`  | Unsupported platform                                    | No      |
| `404`  | Handle does not exist                                   | No      |
| `422`  | Invalid handle format                                   | No      |
| `429`  | Daily quota exceeded (`quota_exceeded`) or rate limit   | No      |
| `503`  | Could not validate the handle right now — retry shortly | No      |