---
title: "Get the status or result of a background research task"
method: GET
path: "/v1/research/{task_id}"
---

# Get the status or result of a background research task

`GET /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.

## Path parameters

- `task_id` string, uuid, required

## Response `200`

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

- ResearchTaskDetail — The full state of a background research task, including status, metadata, the original request input, and the final result once complete.
  - `id` string, uuid, required — Unique identifier for the background research task.
  - `task_type` 'research', required — The task type.
  - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required — The status of a background research task.
  - `created_at` string, date-time, required — When the task was created, in RFC 3339 format.
  - `updated_at` string, date-time, nullable, required — When the task was last updated, in RFC 3339 format. `null` if the task has not yet started running.
  - `completed_at` string, date-time, nullable, required — When the task reached a terminal status, in RFC 3339 format. `null` if the task has not yet completed, failed, or been cancelled.
  - `error` string, nullable, required — A diagnostic message when `status` is `failed`. `null` for all other statuses.
  - `input` ResearchTaskInput, required — The original request parameters submitted for the background research task.
    - `input` string, required — The research question that was submitted.
    - `research_effort` 'lite' | 'standard' | 'deep' | 'exhaustive' | 'frontier', required — The research effort level that was submitted.
    - `background` boolean, required — Whether background mode was requested.
    - `output_schema` object, nullable, required — The structured output schema that was submitted, if any.
    - `source_control` object, nullable, required — The source control configuration that was submitted, if any.
    - `type` 'research', required — The task type.
  - `result` ResearchOutput, required — The research output containing the answer and sources.
    - `output` object, required — An object containing the content, content type, and source list.
      - `content` union, required — 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.
        - string
        - object
      - `content_type` 'text' | 'object', required — The format of the content field.
      - `sources` object[], required — A list of web sources used to generate the answer.
        - `url` string, required — The URL of the source webpage.
        - `title` string — The title of the source webpage.
        - `snippets` string[] — Relevant excerpts from the source page that were used in generating the answer.
    - `warnings` string[], required — A list of warnings generated during research, such as source access issues or partial results. Empty when no warnings occurred.

## Other responses

- `401` — Unauthorized. Problems with API key.
- `403` — Forbidden. The API key is not authorized to access this task.
- `404` — Not found. The task ID does not exist.
- `500` — Internal Server Error during authentication/authorization middleware.

---

[API](https://skmtc.net/you/apis/you-com-research-api.md) · [All operations](https://skmtc.net/you/apis/you-com-research-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/you/you-com-research-api/versions/24d9e2eb5297/schema)