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

> List scouting tasks for this user.

Returns scouting tasks created with the API for the authenticated user.
Each scout includes lightweight metadata including status (active, paused, or done).

Supports optional cursor-based pagination and status filtering.
If page\_size is not provided, returns all matching scouts.

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

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

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

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

## Advanced Example

<Accordion title="Using Pagination and Status Filtering">
  Use cursor-based pagination to efficiently fetch scouts in batches, with optional filtering by status.

  <CodeGroup>
    ```bash cURL theme={null}
    # First page with status filter
    curl --request GET \
      --url 'https://api.yutori.com/v1/scouting/tasks?page_size=20&status=active' \
      --header 'X-API-Key: YOUR_API_KEY'

    # Next page using cursor from previous response
    curl --request GET \
      --url 'https://api.yutori.com/v1/scouting/tasks?page_size=20&cursor=eyJjcmVhdGVkX2F0Ijo...' \
      --header 'X-API-Key: YOUR_API_KEY'
    ```

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

    # First page with status filter
    response = requests.get(
        "https://api.yutori.com/v1/scouting/tasks",
        headers={"X-API-Key": "YOUR_API_KEY"},
        params={"page_size": 20, "status": "active"}
    )
    data = response.json()

    # Paginate through all results
    while data.get("has_more"):
        response = requests.get(
            "https://api.yutori.com/v1/scouting/tasks",
            headers={"X-API-Key": "YOUR_API_KEY"},
            params={"page_size": 20, "cursor": data["next_cursor"]}
        )
        data = response.json()
    ```

    ```javascript JavaScript theme={null}
    // First page with status filter
    const response = await fetch(
      "https://api.yutori.com/v1/scouting/tasks?page_size=20&status=active",
      {
        method: "GET",
        headers: { "X-API-Key": "YOUR_API_KEY" }
      }
    );
    let data = await response.json();

    // Paginate through all results
    while (data.has_more) {
      const nextResponse = await fetch(
        `https://api.yutori.com/v1/scouting/tasks?page_size=20&cursor=${data.next_cursor}`,
        {
          method: "GET",
          headers: { "X-API-Key": "YOUR_API_KEY" }
        }
      );
      data = await nextResponse.json();
    }
    ```
  </CodeGroup>

  ### Response Format

  The response includes pagination metadata and summary statistics:

  ```json theme={null}
  {
    "scouts": [...],
    "total": 125,
    "summary": {
      "active": 80,
      "paused": 30,
      "done": 15
    },
    "page_size": 20,
    "has_more": true,
    "prev_cursor": null,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQxMDozMDowMFoiLCJpZCI6IjEyMzQ1In0="
  }
  ```

  ### Query Parameters

  | Parameter   | Type    | Description                                                         |
  | ----------- | ------- | ------------------------------------------------------------------- |
  | `page_size` | integer | Number of scouts per page. If omitted, returns all matching scouts. |
  | `cursor`    | string  | Cursor from a previous response for pagination.                     |
  | `status`    | string  | Filter by status: `active`, `paused`, or `done`.                    |
</Accordion>


## OpenAPI

````yaml GET /v1/scouting/tasks
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.yutori.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /v1/scouting/tasks:
    get:
      tags:
        - Scouting
      summary: Get Scouts
      description: List scouting tasks for this user.
      operationId: get_scouts_v1_scouting_tasks_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - enum:
                  - active
                  - paused
                  - done
                type: string
              - type: 'null'
            description: Filter by scout status
            title: Status
          description: Filter by scout status
        - 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/ScoutListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ScoutListResponse:
      properties:
        scouts:
          items:
            $ref: '#/components/schemas/ScoutListItem'
          type: array
          title: Scouts
        total:
          type: integer
          title: Total
          description: Total count of all scouts (active + paused + done)
          default: 0
        filtered_total:
          type: integer
          title: Filtered Total
          description: Count of scouts matching the current filter
          default: 0
        summary:
          anyOf:
            - $ref: '#/components/schemas/ScoutsSummary'
            - 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:
        - scouts
      title: ScoutListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ScoutListItem:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        query:
          type: string
          title: Query
        display_name:
          type: string
          title: Display Name
        status:
          type: string
          enum:
            - active
            - paused
            - done
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        next_output_timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Output Timestamp
        output_interval:
          type: integer
          title: Output Interval
          description: Run interval in seconds
        rejection_reason:
          anyOf:
            - $ref: '#/components/schemas/RejectionReason'
            - type: 'null'
      type: object
      required:
        - id
        - query
        - display_name
        - status
        - created_at
        - next_output_timestamp
        - output_interval
      title: ScoutListItem
      description: Lightweight scout metadata for list endpoints.
    ScoutsSummary:
      properties:
        active:
          type: integer
          title: Active
          description: Number of active scouts
        paused:
          type: integer
          title: Paused
          description: Number of paused scouts
        done:
          type: integer
          title: Done
          description: Number of completed scouts
      type: object
      required:
        - active
        - paused
        - done
      title: ScoutsSummary
      description: Summary counts of scouts by 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

````