Skip to content
Aspire Atlas

Quickstart

Steps to retrieve a creator using a Service Account token.

1. Get a token

Section titled “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 for the token model.

2. Read a creator

Section titled “2. Read a creator”
Terminal window
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/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

Section titled “3. Handling a 202 response”

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

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.

4. Read several creators at once

Section titled “4. Read several creators at once”
Terminal window
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

Section titled “Next steps”