> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://you.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://you.com/docs/_mcp/server. # Research Task Status GET https://api.you.com/v1/research/{task_id} 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. Reference: https://you.com/docs/api-reference/research/v1-research-task ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: research version: 1.0.0 paths: /v1/research/{task_id}: get: operationId: getResearchTask summary: Get the status or result of a background research task description: >- 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. tags: - '' parameters: - name: task_id in: path description: The unique identifier of the background research task. required: true schema: type: string format: uuid - name: X-API-Key in: header description: >- A unique API Key is required to authorize API access. [Get your API Key with free credits](https://you.com/platform). required: true schema: type: string responses: '200': description: The current status and, if completed, the result of the task. content: application/json: schema: $ref: '#/components/schemas/ResearchTask' '401': description: Unauthorized. Problems with API key. content: application/json: schema: $ref: '#/components/schemas/GetResearchTaskRequestUnauthorizedError' '403': description: Forbidden. The API key is not authorized to access this task. content: application/json: schema: $ref: '#/components/schemas/GetResearchTaskRequestForbiddenError' '404': description: Not found. The task ID does not exist. content: application/json: schema: $ref: '#/components/schemas/GetResearchTaskRequestNotFoundError' '500': description: >- Internal Server Error during authentication/authorization middleware. content: application/json: schema: $ref: '#/components/schemas/GetResearchTaskRequestInternalServerError' servers: - url: https://api.you.com description: Production components: schemas: ResearchTaskType: type: string enum: - research description: The task type. title: ResearchTaskType ResearchTaskStatus: type: string enum: - queued - running - completed - failed - cancelled description: The status of a background research task. title: ResearchTaskStatus ResearchOutputOutputContent: oneOf: - type: string - type: object additionalProperties: description: Any type description: >- The comprehensive response with inline citations. By default, content is a Markdown string with numbered citations that reference the items in the sources array. When `output_schema` is provided, content is a JSON object that conforms to the requested schema. title: ResearchOutputOutputContent ResearchOutputOutputContentType: type: string enum: - text - object description: The format of the content field. title: ResearchOutputOutputContentType ResearchOutputOutputSourcesItems: type: object properties: url: type: string description: The URL of the source webpage. title: type: string description: The title of the source webpage. snippets: type: array items: type: string description: >- Relevant excerpts from the source page that were used in generating the answer. required: - url title: ResearchOutputOutputSourcesItems ResearchOutputOutput: type: object properties: content: $ref: '#/components/schemas/ResearchOutputOutputContent' description: >- The comprehensive response with inline citations. By default, content is a Markdown string with numbered citations that reference the items in the sources array. When `output_schema` is provided, content is a JSON object that conforms to the requested schema. content_type: $ref: '#/components/schemas/ResearchOutputOutputContentType' description: The format of the content field. sources: type: array items: $ref: '#/components/schemas/ResearchOutputOutputSourcesItems' description: A list of web sources used to generate the answer. required: - content - content_type - sources description: An object containing the content, content type, and source list. title: ResearchOutputOutput ResearchOutput: type: object properties: output: $ref: '#/components/schemas/ResearchOutputOutput' description: An object containing the content, content type, and source list. required: - output description: The research output containing the answer and sources. title: ResearchOutput ResearchTask: type: object properties: task_id: type: string format: uuid description: Unique identifier for the background research task. type: $ref: '#/components/schemas/ResearchTaskType' description: The task type. status: $ref: '#/components/schemas/ResearchTaskStatus' stream_url: type: string description: The URL path for the Server-Sent Events stream for this task. created_at: type: string format: date-time description: When the task was created, in RFC 3339 format. result: oneOf: - $ref: '#/components/schemas/ResearchOutput' - type: 'null' description: >- The final research result when `status` is `completed`. `null` while the task is queued or running. error: type: - string - 'null' description: >- A diagnostic message when `status` is `failed`. `null` for all other statuses. required: - task_id - type - status - stream_url - created_at description: >- A handle for a background research task, including its current status and final result once complete. title: ResearchTask GetResearchTaskRequestUnauthorizedError: type: object properties: detail: type: string description: Error detail message. title: GetResearchTaskRequestUnauthorizedError GetResearchTaskRequestForbiddenError: type: object properties: detail: type: string title: GetResearchTaskRequestForbiddenError GetResearchTaskRequestNotFoundError: type: object properties: detail: type: string title: GetResearchTaskRequestNotFoundError GetResearchTaskRequestInternalServerError: type: object properties: detail: type: string title: GetResearchTaskRequestInternalServerError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- A unique API Key is required to authorize API access. [Get your API Key with free credits](https://you.com/platform). ``` ## Examples **Response** ```json { "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 } ``` **SDK Code** ```python getResearchTask_example import requests url = "https://api.you.com/v1/research/task_id" headers = {"X-API-Key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript getResearchTask_example const url = 'https://api.you.com/v1/research/task_id'; const options = {method: 'GET', headers: {'X-API-Key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go getResearchTask_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.you.com/v1/research/task_id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("X-API-Key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java getResearchTask_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.you.com/v1/research/task_id") .header("X-API-Key", "") .asString(); ``` ```csharp getResearchTask_example using RestSharp; var client = new RestClient("https://api.you.com/v1/research/task_id"); var request = new RestRequest(Method.GET); request.AddHeader("X-API-Key", ""); IRestResponse response = client.Execute(request); ``` ```swift getResearchTask_example import Foundation let headers = ["X-API-Key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.you.com/v1/research/task_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```