---
title: "Create A Task"
method: POST
path: "/v1/research/tasks"
tags: ["Research"]
---

# Create A Task

`POST /v1/research/tasks`

Launches a one-time research task on the web.

## Request body

- CreateResearchTaskRequest
  - `output_schema` object, nullable — JSON Schema for structured output. Takes precedence over task_spec if both provided.
  - `task_spec` TaskSpec
    - `output_schema` JsonSchemaSpec
      - `type` 'json'
      - `json_schema` object, nullable — A JSON Schema object defining the structure
  - `used_deprecated_task_spec` boolean
  - `query` string, required — String describing the research task in natural language.
  - `user_timezone` string — User's timezone for contextual awareness (e.g. 'America/Los_Angeles')
  - `user_location` string, nullable — User's coarse location in the format: city, region_code, country_name
  - `skip_email` boolean — If true, email notifications will be skipped and only webhook notifications will be sent. Default: true (sends webhooks only).
  - `webhook_url` string, nullable — Optional webhook URL to receive results when the research task completes
  - `webhook_format` 'scout' | 'slack' | 'zapier' — Webhook payload format. Slack incoming webhook URLs require 'slack'.

## Response `200`

Successful Response

- CreateResearchTaskResponse — Response for creating a research task.
  - `task_id` string, required — Unique identifier for this research task
  - `view_url` string, required — URL to view task progress and results
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required — Current status of the research task
  - `webhook_url` string, nullable — Echoes the webhook URL configured for this task, if provided

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/yutori/apis/fastapi.md) · [All operations](https://skmtc.dev/yutori/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yutori/fastapi/revisions/ef669f82d5bc/schema)