Research Task Status | You.com

{
  "task_id": "f1e2d3c4-0000-0000-0000-000000000000",
  "type": "research",
  "status": "completed",
  "stream_url": "/v1/research/f1e2d3c4-0000-0000-0000-000000000000/stream",
  "created_at": "2026-06-26T00:00:00Z",
  "result": {
    "output": {
      "content": "Over the past decade, some global cities have shown improvements in air quality due to specific actions. Beijing, for example, made significant strides in improving its air quality through coordinated control measures with surrounding areas, collaborative planning, unified standards, joint emergency responses, and information sharing [[1]].\n",
      "content_type": "text",
      "sources": [
        {
          "url": "https://sustainablemobility.iclei.org/air-pollution-beijing/",
          "title": "Clearing the skies - how Beijing tackled air pollution",
          "snippets": [
            "Beijing has made remarkable strides in recent years to improve its air quality."
          ]
        }
      ]
    }
  },
  "error": null
}

Retrieve the current status of a background research task. While the task is in progress, the result field is null. Once the task reaches completed, the full research result is returned in result. If the task fails, status is failed and error contains a diagnostic message.

Authentication

X-API-Keystring

A unique API Key is required to authorize API access. Get your API Key with free credits.

A unique API Key is required to authorize API access. [Get your API Key with free credits](https://you.com/platform).

Path parameters

task_idstringRequiredformat: "uuid"

The unique identifier of the background research task.

Response

The current status and, if completed, the result of the task.

task_idstringformat: "uuid"

Unique identifier for the background research task.

typeenum

The task type.

statusenum

The status of a background research task.

stream_urlstring

The URL path for the Server-Sent Events stream for this task.

created_atdatetime

When the task was created, in RFC 3339 format.

resultobject or null

The final research result when status is completed. null while the task is queued or running.

errorstring or null

A diagnostic message when status is failed. null for all other statuses.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

$	curl https://api.you.com/v1/research/task_id \
>	-H "X-API-Key: <apiKey>"