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

# Asynchronous tasks

> Submit, wait briefly, and resume SocQ collections safely.

# Asynchronous tasks

Every collection endpoint creates a background task:

```text theme={"system"}
submit -> task_id -> queued -> running -> succeeded
                                   \-> failed
```

## MCP flow

Compact MCP submits through `socq_execute`; typed MCP submits through a tool such as `socq_youtube_comments`. Both return the same task model.

```json theme={"system"}
{
  "task_id": "TASK_ID",
  "status": "running"
}
```

MCP waits zero seconds by default. Set `wait_seconds` on `socq_execute`, or `_wait_seconds` on a typed tool, to wait for at most 30 seconds.

If the task is still `queued` or `running`, keep its ID and call:

```json theme={"system"}
{
  "task_id": "TASK_ID",
  "limit": 100
}
```

with `socq_get_task` until it succeeds or fails.

<Warning>
  A client-side timeout does not cancel the SocQ task. Query the same task ID instead of submitting and paying for a duplicate collection.
</Warning>

## Safe retries

Use an idempotency key when a network or client failure might cause a submission retry. The same user, key, endpoint, and input return the original task. Reusing a key with different input returns a conflict.

```json theme={"system"}
{
  "endpoint": "youtube/comments",
  "input": {
    "urls": ["https://www.youtube.com/watch?v=VIDEO_ID"]
  },
  "idempotency_key": "youtube-comments-research-20260721"
}
```

## CLI flow

The CLI performs client-side polling without holding an API request open:

```bash theme={"system"}
socq task wait TASK_ID --timeout 180
```

Continue with [Pagination and files](/integrations/pagination-files) after the task succeeds.