# Quickstart

> How to make a first API call, including handling the 202 response on an uncached read.

Steps to retrieve a creator using a Service Account token.

## 1. Get a token

Service Account tokens are issued by Aspire; request one from your Aspire contact. The token,
prefixed `asp_sa_`, is returned **exactly once, at creation**. Only a hash is stored on Aspire's
side, so the token cannot be re-read later. Store it as a secret. See [API tokens](/docs/guides/api-tokens/) for the token model.

## 2. Read a creator

```sh
curl -i \
  -H "Authorization: Bearer asp_sa_..." \
  https://atlas.aspire.io/api/v1/creators/instagram/somehandle
```

If the creator has already been processed, it is returned, wrapped in `data`:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "channels": [
      {
        "username": "somehandle",
        "followersCount": 12840,
        "instagram": { "mediaCount": 214 }
      }
    ]
  }
}
```

(Trimmed for brevity — the real response includes every field the API publishes for this creator.)

## 3. Handling a 202 response

If the creator has not been processed, processing begins and a retry time is returned:

```http
HTTP/1.1 202 Accepted
Retry-After: 20

{ "fetching": [{ "id": "somehandle", "retryAfter": "2027-01-15T21:45:10Z" }] }
```

A 202 is not a failure. Wait the number of seconds specified in the `Retry-After` header, then
re-request the same URL. Repeat until the response is `200` (data available) or `404`. On a `404`,
retry with backoff only if `error.details.retryable` is `true` — absent or `false` means stop.

:::caution[Provisional]
Typical discovery duration is still being measured.
:::

## 4. Read several creators at once

```sh
curl -H "Authorization: Bearer asp_sa_..." \
  "https://atlas.aspire.io/api/v1/creators?ids=instagram:alice,instagram:bob"
```

A batch request always returns `200`, with each identifier assigned to one of three buckets:
ready (`data`), in flight (`fetching`), or not obtainable (`unavailable`).

## Next steps

- [Rate limits](/docs/reference/rate-limits/) — the request budget and 429 behavior.