Keys, permissions and credits

Authenticate each request

Send Authorization: Bearer YOUR_API_KEY. Create, expire and revoke Keys in Developer settings. A revoked or expired Key cannot continue reading data, including cached pages. Keep secrets out of URLs, source control and browser code.

Choose two permissions

• data:read reads your accessible tracking accounts, followers, following and detected changes, plus reusable public data. It is enabled by default.
• data:fetch allows explicitly budgeted online queries, in addition to data:read. It is off by default.

A personal Key follows your current and future readable tracking range. A Key cannot grant more access than your account has. Connection permissions and list rights are checked on each request. Plugin connections use the same permissions through OAuth on the MCP resource. An MCP access token cannot be reused as a REST API Key.

Set a spending cap

The five GET operations spend no new collection credits. POST /queries uses your existing Instoryview wallet and must fit all three limits: its maxCredits, your daily API cap, and your available wallet balance.

The daily cap is shared across all your Keys and connections. Creating or rotating a Key does not reset it. API budget days use UTC. Credits reserved for an unfinished request remain reserved until its outcome is settled.

The budget covers the whole logical query, including any necessary profile lookup and billable source calls. A failed or missing-account lookup may still have a source cost. Check meta.creditsUsed on both success and errors; null means the final cost is not yet confirmed.

Retry the same logical query

Each POST requires an Idempotency-Key. Keep its value and the exact request body until the result is confirmed. Replaying a completed query returns its original data and original total creditsUsed without charging again.

• request_in_progress: respect Retry-After and resend the same POST with the same key. Limit automatic recovery to 60 seconds.
• query_outcome_unknown: stop automatic retries, preserve the key, and check your usage or recover manually later with that same key.
• idempotency_conflict: the key was already used with a different body. Correct your recovery request; do not silently launch a new paid operation.
• result_expired: the stored result can no longer be returned. The old key must not start another collection.

For an online next page, use the returned online cursor with a new key and a new explicit maxCredits. Stored-read cursors and online-query cursors cannot be mixed.

Common errors

Errors use {error:{code,message},meta:{requestId,creditsUsed}}. Keep requestId when contacting support.

• 401 unauthorized: update your Key or reconnect.
• 403 insufficient_scope or list_not_authorized: check query permission or your rights to that list.
• 404 snapshot_unavailable: no readable retained tracking snapshot exists; it does not mean zero followers.
• 404 data_unavailable: no reusable public data exists. An online query is a separate choice.
• 402 budget_exceeded or insufficient_credits: change the budget yourself before a new query.
• 409 data_changed or account_changed: restart the stored read after checking the account.
• 410 cursor_expired: restart a stored read; never restart a paid collection automatically.
• 429 rate_limited: respect Retry-After.
• 503 upstream_unavailable: keep the request identifier; paid recovery uses the original idempotency key.

An error never authorizes a client to change a read into an online query.