# Harnyx Research API reference (generated)

Generated from FastAPI OpenAPI.

## Authentication and hosts

Public integrations use `https://api.harnyx.ai` with `Authorization: Bearer <HARNYX_API_KEY>`.
Signing in to Developer Console does not authenticate browser requests to that public API host.

This reference covers the public bearer-authenticated Research API. The machine-readable contract is available at [research.openapi.json](/api/research.openapi.json).

## Domains
- [research](#research)
  - [GET /v1/research/tasks](#endpoint-get-v1-research-tasks)
  - [POST /v1/research/tasks](#endpoint-post-v1-research-tasks)
  - [GET /v1/research/tasks/{task_id}](#endpoint-get-v1-research-tasks-task_id)

## research

### tasks

<a id="endpoint-get-v1-research-tasks"></a>
#### GET /v1/research/tasks

List Research Tasks

**Auth**: PlatformApiKey

**Parameters**
| Param | In | Req | Notes |
| --- | --- | --- | --- |
| `cursor` | query | opt | `string` (nullable) |
| `limit` | query | opt | `integer` (default: 50) |

**Responses**
`200` Successful Response
Content-Type: `application/json`
Body: [ResearchTaskPage](#model-researchtaskpage)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `items` |  |  | req | array[[ResearchTaskSummary](#model-researchtasksummary)] |
|  | `created_at` |  | req | `string` (format: date-time) |
|  | `finished_at` |  | req | `string` (format: date-time; nullable) |
|  | `id` |  | req | `string` (format: uuid) |
|  | `input_preview` |  | req | `string` |
|  | `status` |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |
| `next_cursor` |  |  | req | `string` (nullable) |

`400` Invalid Research Task cursor.
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`401` Platform API-key authentication failed.
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

Response headers
| Header | Notes |
| --- | --- |
| `WWW-Authenticate` | `string` — Bearer authentication challenge when API-key authentication fails. |

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`422` Request validation failed (`error_code: validation_failed`).
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |


<a id="endpoint-post-v1-research-tasks"></a>
#### POST /v1/research/tasks

Create Research Task

**Auth**: PlatformApiKey

**Headers**
| Header | Req | Notes |
| --- | --- | --- |
| `Idempotency-Key` | opt | `string` (nullable) |

**Request**
Content-Type: `application/json`
Body: [ResearchTaskCreateRequest](#model-researchtaskcreaterequest)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `include_raw_tool_calls` |  |  | opt | `boolean` (default: False) |
| `input` |  |  | req | `string` |
| `output_schema` |  |  | opt | [JsonObject-Input](#model-jsonobject-input) (nullable) |
| `stream` |  |  | opt | `boolean` (default: False) |

**Responses**
`200` Current task state, recorded tool-call progress and the settled result as named SSE events.
Content-Type: `text/event-stream`
Body: oneOf: [ResearchTaskStateEvent](#model-researchtaskstateevent) OR [ResearchToolCallEvent](#model-researchtoolcallevent)

(no documented fields)

`202` Research Task accepted.
Content-Type: `application/json`
Body: [ResearchTaskResponse](#model-researchtaskresponse)

Response headers
| Header | Notes |
| --- | --- |
| `Location` | `string` — Relative URL for polling the accepted Research Task. |

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `citations` |  |  | req | array[[ResearchTaskCitation](#model-researchtaskcitation) (nullable)] (nullable) |
|  | `excerpts` |  | req | array[`string`] |
|  | `title` |  | req | `string` (nullable) |
|  | `url` |  | req | `string` |
| `created_at` |  |  | req | `string` (format: date-time) |
| `credits_charged` |  |  | req | `string` (nullable) |
| `error` |  |  | req | [ResearchTaskFailure](#model-researchtaskfailure) (nullable) |
|  | `code` |  | req | [ResearchTaskFailureCode](#model-researchtaskfailurecode) |
|  | `message` |  | req | `string` |
| `finished_at` |  |  | req | `string` (format: date-time; nullable) |
| `id` |  |  | req | `string` (format: uuid) |
| `input` |  |  | req | `string` |
| `output` |  |  | req | anyOf: `string` OR [JsonValue-Output](#model-jsonvalue-output) OR `null` |
| `output_schema` |  |  | opt | [JsonObject-Output](#model-jsonobject-output) (nullable) |
| `status` |  |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |

`400` Invalid request or Idempotency-Key.
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`401` Platform API-key authentication failed.
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

Response headers
| Header | Notes |
| --- | --- |
| `WWW-Authenticate` | `string` — Bearer authentication challenge when API-key authentication fails. |

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`409` Idempotency conflict, account task limit, or invalid account status.
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`422` Request validation failed (`error_code: validation_failed`).
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |


#### {task_id}

<a id="endpoint-get-v1-research-tasks-task_id"></a>
##### GET /v1/research/tasks/{task_id}

Get Research Task

**Auth**: PlatformApiKey

**Parameters**
| Param | In | Req | Notes |
| --- | --- | --- | --- |
| `task_id` | path | req | `string` (format: uuid) |
| `include_raw_tool_calls` | query | opt | `boolean` (default: False) |

**Responses**
`200` Current task state, recorded tool-call progress and the settled result as named SSE events.
Content-Type: `application/json`
Body: [ResearchTaskResponse](#model-researchtaskresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `citations` |  |  | req | array[[ResearchTaskCitation](#model-researchtaskcitation) (nullable)] (nullable) |
|  | `excerpts` |  | req | array[`string`] |
|  | `title` |  | req | `string` (nullable) |
|  | `url` |  | req | `string` |
| `created_at` |  |  | req | `string` (format: date-time) |
| `credits_charged` |  |  | req | `string` (nullable) |
| `error` |  |  | req | [ResearchTaskFailure](#model-researchtaskfailure) (nullable) |
|  | `code` |  | req | [ResearchTaskFailureCode](#model-researchtaskfailurecode) |
|  | `message` |  | req | `string` |
| `finished_at` |  |  | req | `string` (format: date-time; nullable) |
| `id` |  |  | req | `string` (format: uuid) |
| `input` |  |  | req | `string` |
| `output` |  |  | req | anyOf: `string` OR [JsonValue-Output](#model-jsonvalue-output) OR `null` |
| `output_schema` |  |  | opt | [JsonObject-Output](#model-jsonobject-output) (nullable) |
| `status` |  |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |

Content-Type: `text/event-stream`
Body: oneOf: [ResearchTaskStateEvent](#model-researchtaskstateevent) OR [ResearchToolCallEvent](#model-researchtoolcallevent)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `citations` |  |  | req | array[[ResearchTaskCitation](#model-researchtaskcitation) (nullable)] (nullable) |
|  | `excerpts` |  | req | array[`string`] |
|  | `title` |  | req | `string` (nullable) |
|  | `url` |  | req | `string` |
| `created_at` |  |  | req | `string` (format: date-time) |
| `credits_charged` |  |  | req | `string` (nullable) |
| `error` |  |  | req | [ResearchTaskFailure](#model-researchtaskfailure) (nullable) |
|  | `code` |  | req | [ResearchTaskFailureCode](#model-researchtaskfailurecode) |
|  | `message` |  | req | `string` |
| `finished_at` |  |  | req | `string` (format: date-time; nullable) |
| `id` |  |  | req | `string` (format: uuid) |
| `input` |  |  | req | `string` |
| `output` |  |  | req | anyOf: `string` OR [JsonValue-Output](#model-jsonvalue-output) OR `null` |
| `output_schema` |  |  | opt | [JsonObject-Output](#model-jsonobject-output) (nullable) |
| `status` |  |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |

`401` Platform API-key authentication failed.
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

Response headers
| Header | Notes |
| --- | --- |
| `WWW-Authenticate` | `string` — Bearer authentication challenge when API-key authentication fails. |

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`404` Research task not found (`error_code: not_found`).
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

`422` Request validation failed (`error_code: validation_failed`).
Content-Type: `application/json`
Body: [ErrorResponse](#model-errorresponse)

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |



## Models

<a id="model-decisionusage"></a>
### Model: DecisionUsage

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `input_tokens` |  |  | opt | `integer` (nullable) |
| `output_tokens` |  |  | opt | `integer` (nullable) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "input_tokens": {
      "anyOf": [
        {
          "minimum": 0.0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Input Tokens"
    },
    "output_tokens": {
      "anyOf": [
        {
          "minimum": 0.0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Output Tokens"
    }
  },
  "title": "DecisionUsage",
  "type": "object"
}
```

</details>

<a id="model-errorbillingdto"></a>
### Model: ErrorBillingDTO

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `actual_cost_provider` |  |  | req | `string` (enum: [openrouter, ai_gateway]) |
| `actual_cost_usd` |  |  | req | `number` |
| `usage` |  |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  | `input_tokens` |  | opt | `integer` (nullable) |
|  | `output_tokens` |  | opt | `integer` (nullable) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "actual_cost_provider": {
      "enum": [
        "openrouter",
        "ai_gateway"
      ],
      "title": "Actual Cost Provider",
      "type": "string"
    },
    "actual_cost_usd": {
      "minimum": 0.0,
      "title": "Actual Cost Usd",
      "type": "number"
    },
    "usage": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/DecisionUsage"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "actual_cost_usd",
    "actual_cost_provider"
  ],
  "title": "ErrorBillingDTO",
  "type": "object"
}
```

</details>

<a id="model-errorresponse"></a>
### Model: ErrorResponse

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `billing` |  |  | opt | [ErrorBillingDTO](#model-errorbillingdto) (nullable) |
|  | `actual_cost_provider` |  | req | `string` (enum: [openrouter, ai_gateway]) |
|  | `actual_cost_usd` |  | req | `number` |
|  | `usage` |  | opt | [DecisionUsage](#model-decisionusage) (nullable) |
|  |  | `input_tokens` | opt | `integer` (nullable) |
|  |  | `output_tokens` | opt | `integer` (nullable) |
| `error_code` |  |  | req | `string` |
| `message` |  |  | req | `string` |

<details>
<summary>JSON schema</summary>

```json
{
  "properties": {
    "billing": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/ErrorBillingDTO"
        },
        {
          "type": "null"
        }
      ]
    },
    "error_code": {
      "title": "Error Code",
      "type": "string"
    },
    "message": {
      "title": "Message",
      "type": "string"
    }
  },
  "required": [
    "error_code",
    "message"
  ],
  "title": "ErrorResponse",
  "type": "object"
}
```

</details>

<a id="model-jsonobject-input"></a>
### Model: JsonObject-Input

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": {
    "$ref": "#/components/schemas/JsonValue-Input"
  },
  "type": "object"
}
```

</details>

<a id="model-jsonobject-output"></a>
### Model: JsonObject-Output

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": {
    "$ref": "#/components/schemas/JsonValue-Output"
  },
  "type": "object"
}
```

</details>

<a id="model-jsonvalue-input"></a>
### Model: JsonValue-Input

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "integer"
    },
    {
      "type": "number"
    },
    {
      "type": "boolean"
    },
    {
      "items": {
        "$ref": "#/components/schemas/JsonValue-Input"
      },
      "type": "array"
    },
    {
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue-Input"
      },
      "type": "object"
    },
    {
      "type": "null"
    }
  ]
}
```

</details>

<a id="model-jsonvalue-output"></a>
### Model: JsonValue-Output

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "integer"
    },
    {
      "type": "number"
    },
    {
      "type": "boolean"
    },
    {
      "items": {
        "$ref": "#/components/schemas/JsonValue-Output"
      },
      "type": "array"
    },
    {
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue-Output"
      },
      "type": "object"
    },
    {
      "type": "null"
    }
  ]
}
```

</details>

<a id="model-researchtaskcitation"></a>
### Model: ResearchTaskCitation

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `excerpts` |  |  | req | array[`string`] |
| `title` |  |  | req | `string` (nullable) |
| `url` |  |  | req | `string` |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "excerpts": {
      "items": {
        "type": "string"
      },
      "title": "Excerpts",
      "type": "array"
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Title"
    },
    "url": {
      "title": "Url",
      "type": "string"
    }
  },
  "required": [
    "url",
    "title",
    "excerpts"
  ],
  "title": "ResearchTaskCitation",
  "type": "object"
}
```

</details>

<a id="model-researchtaskcreaterequest"></a>
### Model: ResearchTaskCreateRequest

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `include_raw_tool_calls` |  |  | opt | `boolean` (default: False) |
| `input` |  |  | req | `string` |
| `output_schema` |  |  | opt | [JsonObject-Input](#model-jsonobject-input) (nullable) |
| `stream` |  |  | opt | `boolean` (default: False) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "include_raw_tool_calls": {
      "default": false,
      "title": "Include Raw Tool Calls",
      "type": "boolean"
    },
    "input": {
      "minLength": 1,
      "title": "Input",
      "type": "string"
    },
    "output_schema": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/JsonObject-Input"
        },
        {
          "type": "null"
        }
      ],
      "description": "JSON Schema Draft 2020-12 for structured output. `$ref` and `$dynamicRef` values must be local fragments beginning with `#`; external references are rejected. Schemas may contain at most 80,000 compact JSON characters."
    },
    "stream": {
      "default": false,
      "title": "Stream",
      "type": "boolean"
    }
  },
  "required": [
    "input"
  ],
  "title": "ResearchTaskCreateRequest",
  "type": "object"
}
```

</details>

<a id="model-researchtaskfailure"></a>
### Model: ResearchTaskFailure

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `code` |  |  | req | [ResearchTaskFailureCode](#model-researchtaskfailurecode) |
| `message` |  |  | req | `string` |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "code": {
      "$ref": "#/components/schemas/ResearchTaskFailureCode"
    },
    "message": {
      "title": "Message",
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "title": "ResearchTaskFailure",
  "type": "object"
}
```

</details>

<a id="model-researchtaskfailurecode"></a>
### Model: ResearchTaskFailureCode

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "enum": [
    "insufficient_credits",
    "execution_timeout",
    "invalid_output",
    "execution_failed"
  ],
  "title": "ResearchTaskFailureCode",
  "type": "string"
}
```

</details>

<a id="model-researchtaskpage"></a>
### Model: ResearchTaskPage

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `items` |  |  | req | array[[ResearchTaskSummary](#model-researchtasksummary)] |
|  | `created_at` |  | req | `string` (format: date-time) |
|  | `finished_at` |  | req | `string` (format: date-time; nullable) |
|  | `id` |  | req | `string` (format: uuid) |
|  | `input_preview` |  | req | `string` |
|  | `status` |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |
| `next_cursor` |  |  | req | `string` (nullable) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "items": {
      "items": {
        "$ref": "#/components/schemas/ResearchTaskSummary"
      },
      "title": "Items",
      "type": "array"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Next Cursor"
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "title": "ResearchTaskPage",
  "type": "object"
}
```

</details>

<a id="model-researchtaskresponse"></a>
### Model: ResearchTaskResponse

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `citations` |  |  | req | array[[ResearchTaskCitation](#model-researchtaskcitation) (nullable)] (nullable) |
|  | `excerpts` |  | req | array[`string`] |
|  | `title` |  | req | `string` (nullable) |
|  | `url` |  | req | `string` |
| `created_at` |  |  | req | `string` (format: date-time) |
| `credits_charged` |  |  | req | `string` (nullable) |
| `error` |  |  | req | [ResearchTaskFailure](#model-researchtaskfailure) (nullable) |
|  | `code` |  | req | [ResearchTaskFailureCode](#model-researchtaskfailurecode) |
|  | `message` |  | req | `string` |
| `finished_at` |  |  | req | `string` (format: date-time; nullable) |
| `id` |  |  | req | `string` (format: uuid) |
| `input` |  |  | req | `string` |
| `output` |  |  | req | anyOf: `string` OR [JsonValue-Output](#model-jsonvalue-output) OR `null` |
| `output_schema` |  |  | opt | [JsonObject-Output](#model-jsonobject-output) (nullable) |
| `status` |  |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "citations": {
      "anyOf": [
        {
          "items": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ResearchTaskCitation"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Citations"
    },
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "credits_charged": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Credits Charged"
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/ResearchTaskFailure"
        },
        {
          "type": "null"
        }
      ]
    },
    "finished_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Finished At"
    },
    "id": {
      "format": "uuid",
      "title": "Id",
      "type": "string"
    },
    "input": {
      "description": "Complete Research Task input.",
      "minLength": 1,
      "title": "Input",
      "type": "string"
    },
    "output": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/components/schemas/JsonValue-Output"
        },
        {
          "type": "null"
        }
      ],
      "description": "Task output: text, structured JSON, or null. Use status to distinguish a pending result from a completed structured null. Structured responses may contain at most 80,000 compact JSON characters; oversized structured responses cause terminal invalid_output failure.",
      "title": "Output"
    },
    "output_schema": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/JsonObject-Output"
        },
        {
          "type": "null"
        }
      ],
      "description": "Structured output schema requested for this Research Task."
    },
    "status": {
      "$ref": "#/components/schemas/ResearchTaskStatus"
    }
  },
  "required": [
    "id",
    "input",
    "status",
    "created_at",
    "finished_at",
    "output",
    "citations",
    "error",
    "credits_charged"
  ],
  "title": "ResearchTaskResponse",
  "type": "object"
}
```

</details>

<a id="model-researchtaskstateevent"></a>
### Model: ResearchTaskStateEvent

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `task` |  |  | req | [ResearchTaskResponse](#model-researchtaskresponse) |
|  | `citations` |  | req | array[[ResearchTaskCitation](#model-researchtaskcitation) (nullable)] (nullable) |
|  |  | `excerpts` | req | array[`string`] |
|  |  | `title` | req | `string` (nullable) |
|  |  | `url` | req | `string` |
|  | `created_at` |  | req | `string` (format: date-time) |
|  | `credits_charged` |  | req | `string` (nullable) |
|  | `error` |  | req | [ResearchTaskFailure](#model-researchtaskfailure) (nullable) |
|  |  | `code` | req | [ResearchTaskFailureCode](#model-researchtaskfailurecode) |
|  |  | `message` | req | `string` |
|  | `finished_at` |  | req | `string` (format: date-time; nullable) |
|  | `id` |  | req | `string` (format: uuid) |
|  | `input` |  | req | `string` |
|  | `output` |  | req | anyOf: `string` OR [JsonValue-Output](#model-jsonvalue-output) OR `null` |
|  | `output_schema` |  | opt | [JsonObject-Output](#model-jsonobject-output) (nullable) |
|  | `status` |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |
| `task_id` |  |  | req | `string` (format: uuid) |
| `type` |  |  | req | `string` (enum: [task.snapshot, task.completed, task.failed]) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "task": {
      "$ref": "#/components/schemas/ResearchTaskResponse"
    },
    "task_id": {
      "format": "uuid",
      "title": "Task Id",
      "type": "string"
    },
    "type": {
      "enum": [
        "task.snapshot",
        "task.completed",
        "task.failed"
      ],
      "title": "Type",
      "type": "string"
    }
  },
  "required": [
    "type",
    "task_id",
    "task"
  ],
  "title": "ResearchTaskStateEvent",
  "type": "object"
}
```

</details>

<a id="model-researchtaskstatus"></a>
### Model: ResearchTaskStatus

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "enum": [
    "queued",
    "in_progress",
    "completed",
    "failed"
  ],
  "title": "ResearchTaskStatus",
  "type": "string"
}
```

</details>

<a id="model-researchtasksummary"></a>
### Model: ResearchTaskSummary

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `created_at` |  |  | req | `string` (format: date-time) |
| `finished_at` |  |  | req | `string` (format: date-time; nullable) |
| `id` |  |  | req | `string` (format: uuid) |
| `input_preview` |  |  | req | `string` |
| `status` |  |  | req | [ResearchTaskStatus](#model-researchtaskstatus) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "created_at": {
      "format": "date-time",
      "title": "Created At",
      "type": "string"
    },
    "finished_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Finished At"
    },
    "id": {
      "format": "uuid",
      "title": "Id",
      "type": "string"
    },
    "input_preview": {
      "description": "First 500 characters of the Research Task input. Exact reads return the complete input.",
      "maxLength": 500,
      "minLength": 1,
      "title": "Input Preview",
      "type": "string"
    },
    "status": {
      "$ref": "#/components/schemas/ResearchTaskStatus"
    }
  },
  "required": [
    "id",
    "input_preview",
    "status",
    "created_at",
    "finished_at"
  ],
  "title": "ResearchTaskSummary",
  "type": "object"
}
```

</details>

<a id="model-researchtoolcallevent"></a>
### Model: ResearchToolCallEvent

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `call_id` |  |  | req | `string` |
| `finished_at` |  |  | req | `string` (format: date-time; nullable) |
| `outcome` |  |  | req | [ToolCallOutcome](#model-toolcalloutcome) (nullable) |
| `raw` |  |  | opt | [ResearchToolCallRaw](#model-researchtoolcallraw) (nullable) |
|  | `request` |  | req | [JsonValue-Output](#model-jsonvalue-output) (nullable) |
|  | `response` |  | req | [JsonValue-Output](#model-jsonvalue-output) (nullable) |
| `started_at` |  |  | req | `string` (format: date-time) |
| `task_id` |  |  | req | `string` (format: uuid) |
| `tool` |  |  | req | `string` (enum: [search_web, search_ai, fetch_page, embed_text, decision_query, llm_chat, test_tool, tooling_info]) |
| `type` |  |  | req | `string` (enum: [tool_call.started, tool_call.completed, tool_call.failed]) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "call_id": {
      "title": "Call Id",
      "type": "string"
    },
    "finished_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Finished At"
    },
    "outcome": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/ToolCallOutcome"
        },
        {
          "type": "null"
        }
      ]
    },
    "raw": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/ResearchToolCallRaw"
        },
        {
          "type": "null"
        }
      ]
    },
    "started_at": {
      "format": "date-time",
      "title": "Started At",
      "type": "string"
    },
    "task_id": {
      "format": "uuid",
      "title": "Task Id",
      "type": "string"
    },
    "tool": {
      "enum": [
        "search_web",
        "search_ai",
        "fetch_page",
        "embed_text",
        "decision_query",
        "llm_chat",
        "test_tool",
        "tooling_info"
      ],
      "title": "Tool",
      "type": "string"
    },
    "type": {
      "enum": [
        "tool_call.started",
        "tool_call.completed",
        "tool_call.failed"
      ],
      "title": "Type",
      "type": "string"
    }
  },
  "required": [
    "type",
    "task_id",
    "call_id",
    "tool",
    "started_at",
    "finished_at",
    "outcome"
  ],
  "title": "ResearchToolCallEvent",
  "type": "object"
}
```

</details>

<a id="model-researchtoolcallraw"></a>
### Model: ResearchToolCallRaw

| 1st level | 2nd level | 3rd level | Req | Notes |
| --- | --- | --- | --- | --- |
| `request` |  |  | req | [JsonValue-Output](#model-jsonvalue-output) (nullable) |
| `response` |  |  | req | [JsonValue-Output](#model-jsonvalue-output) (nullable) |

<details>
<summary>JSON schema</summary>

```json
{
  "additionalProperties": false,
  "properties": {
    "request": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/JsonValue-Output"
        },
        {
          "type": "null"
        }
      ]
    },
    "response": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/JsonValue-Output"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "request",
    "response"
  ],
  "title": "ResearchToolCallRaw",
  "type": "object"
}
```

</details>

<a id="model-toolcalloutcome"></a>
### Model: ToolCallOutcome

(no documented fields)

<details>
<summary>JSON schema</summary>

```json
{
  "description": "High-level outcome for a tool invocation.",
  "enum": [
    "ok",
    "provider_error",
    "budget_exceeded",
    "internal_error",
    "timeout"
  ],
  "title": "ToolCallOutcome",
  "type": "string"
}
```

</details>