Asynchronous tasks
Every collection endpoint creates a background task:
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.
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:
with socq_get_task until it succeeds or fails.
A client-side timeout does not cancel the SocQ task. Query the same task ID instead of submitting and paying for a duplicate collection.
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.
CLI flow
The CLI performs client-side polling without holding an API request open:
Continue with Pagination and files after the task succeeds.
