Research Task Status | You.com

{
  "id": "f1e2d3c4-0000-0000-0000-000000000000",
  "task_type": "research",
  "status": "completed",
  "created_at": "2026-06-26T00:00:00Z",
  "updated_at": "2026-06-26T00:00:30Z",
  "completed_at": "2026-06-26T00:00:30Z",
  "error": null,
  "input": {
    "input": "Which global cities improved air quality the most over the past 10 years, and what measurable actions contributed?",
    "research_effort": "standard",
    "background": true,
    "output_schema": {},
    "source_control": {},
    "type": "research"
  },
  "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."
          ]
        }
      ]
    },
    "warnings": []
  }
}

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.

idstringformat: "uuid"

Unique identifier for the background research task.

task_typeenum

The task type.

statusenum

The status of a background research task.

created_atdatetime

When the task was created, in RFC 3339 format.

updated_atdatetime or null

When the task was last updated, in RFC 3339 format. null if the task has not yet started running.

completed_atdatetime or null

When the task reached a terminal status, in RFC 3339 format. null if the task has not yet completed, failed, or been cancelled.

errorstring or null

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

inputobject

The original request parameters submitted for the background research task.

resultobject or null

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

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>"