---
title: "Create Scout Task"
method: POST
path: "/v1/scouting/tasks"
tags: ["Scouting"]
---

# Create Scout Task

`POST /v1/scouting/tasks`

## Request body

- CreateScoutRequestAPI
  - `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 what to monitor in natural language. This is typically what a user types into the Scouts web UI (without any frequency preferences).
  - `output_interval` integer — Interval in seconds of how often to run the task. This must be >= 1800 (= 30 minutes). On the web UI, this is inferred from what the user types into the new scout input (e.g. "daily at 9am"). Recommended: 86400 (daily) or 3600 (hourly).
  - `start_timestamp` integer — Unix timestamp (past, present, or future) of when the scout should start running. If past, present, or up to 30 min in the future, the scout will start running immediately. Else, the scout will start running at the specified timestamp.
  - `user_timezone` string — String indicating the user's timezone (e.g. "America/Los_Angeles") On the web UI, this is inferred from the browser's timezone. Default: "America/Los_Angeles".
  - `user_location` string, nullable — String indicating the user's coarse location in the format: city, region_code, country_name. On the web UI, this is inferred from the browser's location. Default: "San Francisco, CA, US".
  - `skip_email` boolean — If true, email notifications will be skipped and only webhook notifications will be sent. Email subscriptions will still be stored but no emails will be sent. Default: true (sends webhooks only).
  - `webhook_url` string, nullable — Optional webhook URL to receive updates for this scout. Creates a webhook subscription for the calling user using webhook_format.
  - `webhook_format` 'scout' | 'slack' | 'zapier' — Webhook payload format to use when webhook_url is provided. Slack incoming webhook URLs require 'slack'.
  - `is_public` boolean — Whether the scout is publicly accessible (true) or private (false). Public scouts can be accessed by anyone via the UUID link. Private scouts can only be accessed by the creator. Default: false (private).

## Response `200`

Successful Response

- CreateScoutResponsePublic — Public API response for scout creation. Excludes internal fields like llm_output.
  - `id` string, uuid, required
  - `query` string, required
  - `query_object` object, nullable
  - `display_name` string, required
  - `next_run_timestamp` string, date-time, nullable, required
  - `user_timezone` string, required
  - `next_output_timestamp` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `completed_at` string, date-time, nullable, required
  - `paused_at` string, date-time, nullable, required
  - `rejection_reason` 'insufficient_prepaid_balance' | 'budget_exceeded' | 'subscription_inactive'
  - `is_public` boolean
  - `view_url` string, nullable — URL to view this scout's details in the API platform dashboard.
  - `webhook_url` string, nullable — Optional webhook URL configured for this scout, if provided at creation time.
  - `output_schema` object, nullable, required — JSON Schema for structured output, if configured

## 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)