Tasks and results
Every SocQ collection runs as a background task:
Compact MCP submits through socq_execute; typed MCP submits through a tool such as socq_youtube_comments. Both return the same task model.
Wait for a task
MCP waits zero seconds by default. Set wait_seconds on socq_execute, or _wait_seconds on a typed tool, to wait for up to 30 seconds.
If the task remains queued or running, keep its ID and call socq_get_task:
The CLI can poll the same task without holding an API request open:
A client-side timeout does not cancel the SocQ task. Resume with the same task ID instead of submitting and paying for a duplicate collection.
Retry a submission safely
Use an idempotency key when a network or client failure might trigger a submission retry. For 24 hours, the same user, key, endpoint, and input return the original task; reusing the key with different input returns a conflict. An unfinished task remains protected after the 24-hour window until it finishes.
Read task results
Successful tasks return records in results.items using the fixed resource-level schema shared by REST, MCP, CLI, SDK, and Skills.
Results retain declared nullable fields and exclude provider-specific implementation details. The optional fields parameter accepts at most 50 comma-separated top-level fields or dot paths. A field is omitted only when the projection did not request it.
Typed MCP tools use _result_fields; the CLI uses optional --result-fields.
When has_more is true, pass next_cursor unchanged to the next socq_get_task call. Stop when the cursor is null or your requested research limit has been reached.
Download source files (advanced)
Use socq_get_files or the CLI to retrieve raw JSONL exports:
File URLs may expire. Most integrations should use paginated task results; source files are available for advanced processing and troubleshooting.
For task status and response fields, see Task status and results and Result files.
