> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yutori.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Research Tasks

> List research tasks for the authenticated user.

Returns research tasks for the authenticated user.
Each task includes lightweight metadata including `task_id`, status, creation time, and dashboard URL.

Supports optional cursor-based pagination and status filtering.
If `page_size` is not provided, returns all research tasks.
Use `status=succeeded` to list tasks with retrievable results.
Status is computed from stored task state without a live workflow lookup, so `running` also covers queued tasks and tasks whose workflow has already failed but isn't yet reconciled. Call `GET /v1/research/tasks/{task_id}` for the authoritative `queued`/`running`/`succeeded`/`failed` status of a single task.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.yutori.com/v1/research/tasks \
    --header 'X-API-Key: YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.yutori.com/v1/research/tasks",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.yutori.com/v1/research/tasks", {
    method: "GET",
    headers: { "X-API-Key": "YOUR_API_KEY" }
  });
  const data = await response.json();
  ```
</RequestExample>

## Pagination and Filtering

Use cursor-based pagination to fetch tasks in batches, with optional filtering by status.

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.yutori.com/v1/research/tasks?page_size=20&status=succeeded' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### Query Parameters

| Parameter   | Type    | Description                                              |
| ----------- | ------- | -------------------------------------------------------- |
| `page_size` | integer | Number of tasks per page. If omitted, returns all tasks. |
| `cursor`    | string  | Cursor from a previous response for pagination.          |
| `status`    | string  | Filter by status: `running`, `succeeded`, or `failed`.   |


## OpenAPI

````yaml GET /v1/research/tasks
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.yutori.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /v1/research/tasks:
    get:
      tags:
        - Research
      summary: List Tasks
      description: List research tasks for the authenticated user.
      operationId: list_research_tasks_v1_research_tasks_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - running
                  - succeeded
                  - failed
                type: string
              - type: 'null'
            description: 'Filter by task status: running, succeeded, or failed.'
            title: Status
          description: 'Filter by task status: running, succeeded, or failed.'
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            title: Page Size
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TaskListResponse:
      properties:
        tasks:
          items:
            $ref: '#/components/schemas/TaskListItem'
          type: array
          title: Tasks
        total:
          type: integer
          title: Total
          description: Total count of all tasks (running + succeeded + failed)
          default: 0
        filtered_total:
          type: integer
          title: Filtered Total
          description: Count of tasks matching the current filter
          default: 0
        summary:
          anyOf:
            - $ref: '#/components/schemas/TaskListSummary'
            - type: 'null'
          description: Counts by status
        page_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Size
          description: Requested page size (null if returning all)
        has_more:
          type: boolean
          title: Has More
          description: Whether more results exist after this page
          default: false
        prev_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev Cursor
          description: Cursor for previous page
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Cursor for next page
      type: object
      required:
        - tasks
      title: TaskListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskListItem:
      properties:
        task_id:
          type: string
          title: Task Id
          description: Unique identifier for this task
        query:
          type: string
          title: Query
          description: Task or research query submitted by the caller
        status:
          type: string
          enum:
            - running
            - succeeded
            - failed
          title: Status
          description: >-
            Lightweight task status for list views, derived from stored task
            state: 'succeeded' (results are retrievable), 'failed' (terminal
            with no retrievable results), or 'running' (everything else).
            Because it is computed without a live workflow lookup, 'running'
            also covers queued tasks and the brief window before a finished
            workflow is reconciled in the database. Call GET
            /v1/{browsing,research}/tasks/{id} for the authoritative
            queued/running/succeeded/failed status of a single task.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the task was created
        view_url:
          type: string
          title: View Url
          description: URL to view this task in the API platform dashboard
        rejection_reason:
          anyOf:
            - $ref: '#/components/schemas/RejectionReason'
            - type: 'null'
          description: >-
            If status is 'failed', the specific billing reason for rejection
            when available
      type: object
      required:
        - task_id
        - query
        - status
        - created_at
        - view_url
      title: TaskListItem
      description: Lightweight one-time task metadata for developer API list endpoints.
    TaskListSummary:
      properties:
        running:
          type: integer
          title: Running
          description: Number of tasks still running
        succeeded:
          type: integer
          title: Succeeded
          description: Number of tasks with retrievable results
        failed:
          type: integer
          title: Failed
          description: Number of terminal tasks without retrievable results
      type: object
      required:
        - running
        - succeeded
        - failed
      title: TaskListSummary
      description: Summary counts of one-time tasks by lightweight list status.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    RejectionReason:
      type: string
      enum:
        - insufficient_prepaid_balance
        - budget_exceeded
        - subscription_inactive
      title: RejectionReason
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header

````