YOyou

Get the status or result of a background research task

Changed on

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.

get/v1/research/{task_id}

Request

Path parameters

task_idstring uuid required

The unique identifier of the background research task.

Response

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

idstring 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_atstring date-time required

When the task was created, in RFC 3339 format.

updated_atstring date-time nullable required

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

completed_atstring 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.

errorstring nullable required

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

Example response

{
  "id": "f1e2d3c4-0000-0000-0000-000000000000",
  "task_type": "research",
  "status": "queued",
  "created_at": "2026-06-26T00:00:00Z",
  "result": {
    "output": {
      "content_type": "text",
      "sources": [
        {
          "url": "https://sustainablemobility.iclei.org/air-pollution-beijing/",
          "title": "Clearing the skies: how Beijing tackled air pollution & what lies ahead",
          "snippets": [
            "The city actively coordinated air pollution control measures with surrounding areas, such as the Beijing-Tianjin-Hebei region."
          ]
        }
      ]
    },
    "warnings": []
  }
}

Changes

  • 24d9e2eb5297Revision changes
    • breaking

      response property completed_at list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property error list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      response property updated_at list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      the response's property type changed from object to no type for status

    • warning

      added the new research enum value to the response property for the response status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

  • dfadf8aeab9bRevision changes
    • info

      endpoint added