# Scrolls (/docs/scrolls)



A scroll is one bounded research run. ViralQuery starts a fresh EVE session, appends the exact
workspace rules and optional prompt, and lets the agent choose documented Scrape Creators searches
inside a tenant-isolated smart-code workstation. The provider request, runtime, archive, and hook
budgets are enforced outside the model.

## Start a scroll [#start-a-scroll]

```bash
curl -X POST https://api.viralquery.com/v1/scrolls \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "weekly-2026-07-10",
    "prompt": "Look for strong organic demos and visual hooks from the last month."
  }'
```

The response is `202 Accepted` with a scroll ID. Reusing the same idempotency key returns the same
scroll instead of starting duplicate work.

Only one scroll can be queued or running for a workspace at a time; start another once it finishes.
There is no per-scroll quota to count down — a scroll draws on your daily AI budget, and you can see
how much of that budget you have used as a percentage via [`GET /v1/usage`](/docs/credits-and-billing#checking-access-and-usage).

## Check status [#check-status]

```bash
curl "https://api.viralquery.com/v1/scrolls?id=$SCROLL_ID" \
  -H "Authorization: Bearer $KEY"
```

Statuses are `queued`, `running`, `completed`, `failed`, or `cancelled`. The response also includes
the current stage, bounded progress, result counts, and a stable failure code when applicable.

The bearer key always determines the workspace. A scroll ID owned by another account is returned as
not found, and no customer API or client operation accepts an account or workspace selector.