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

# Async jobs

> Searches and expansions run in the background: how to wait for them and which statuses mean done.

> Agents: the full documentation index is at [/llms.txt](https://docs.revcenter.ai/llms.txt).

Launching a search (`POST /v1/projects/{id}/searches`) and expanding (`POST /v1/projects/{id}/expand`) return
`202` with a `search_id` at once. The work runs in the background, usually for a few minutes. Every other call
answers when it is done.

## Waiting

Poll `GET /v1/searches/{search_id}` every 10 to 30 seconds until `status` is no longer `queued` or `running`.

| `status` | Meaning | Done? |
| - | - | - |
| `queued` | Waiting to start | No |
| `running` | Working; `stage` says where | No |
| `stalled` | Marked running but no activity for 3 minutes | Stop waiting; check again later or contact support |
| `complete` | Finished; `outcome` and `delivered` are set | Yes |
| `failed` | Stopped by an error; `stop_reason` says why. A launch that fails to start gives its credit back | Yes |
| `stopped` | Stopped before finishing; `stop_reason` says why | Yes |

Treat the set as open: if you see a status not listed here, stop waiting and treat it as finished. `stage`
and `stop_reason` are informational and can gain values; don't branch on them.

The CLI and MCP do the polling for you: `revcenter status <search_id> --wait` checks every 10 seconds for up to
15 minutes, and `wait_for_search` every 10 seconds for up to `timeout_seconds` (default 600). Both return as
soon as `status` is anything other than `queued` or `running`.

```json theme={null}
{
  "id": "…",
  "status": "complete",
  "stage": null,
  "stop_reason": "target_reached",
  "outcome": "Shortlist ready",
  "profiles_read": 214,
  "delivered": 12,
  "database_only": false,
  "expansion": false
}
```

`outcome` is `Shortlist ready` (6 or more delivered), `Poor yield` (1 to 5) or `No results` (0), and is set
only when `status` is `complete`. See [searches and shortlists](/guides/searches).

## Only one at a time per project

While a search on a project runs, expanding that project and applying scoring changes to its searches return
`409 search_running`. Wait for it to finish first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.