---
title: "Run analysis"
method: POST
path: "/api/v1/analysis"
tags: ["Analysis"]
---

# Run analysis

`POST /api/v1/analysis`

## Request

- Base URL: `https://botsee.io`
- URL: `https://botsee.io/api/v1/analysis`
- Auth: HTTP bearer

Includes persona context by default so answers reflect the buyer's needs: one sample per question/model, not an average. Set include_persona to false for a question-only benchmark. Generated personas use buyer language rather than explicit homepage product terminology. dry_run previews counts, known brand warnings, and a planning credit range for free (200, no jobs). Starting returns 202; poll GET /api/v1/analysis/:uuid. Actual usage and retries can exceed the estimate; it is not a spending cap.

## Request body

- object
  - `dry_run` boolean: Free preview without creating a run, jobs, or charges
  - `include_persona` boolean: Include persona context with each question; false runs a question-only benchmark
  - `models` unknown[]: AI models: openai-search (ChatGPT with web search), openai (ChatGPT without web search), claude, perplexity, gemini, grok
    - unknown
  - `scope` string: Scope: 'site', 'customer_type', 'persona', or 'questions'
  - `site_uuid` string, required: Site UUID to analyze
  - `target_uuids` unknown[]: Required for non-site scope. UUIDs of customer types, personas, or questions.
    - unknown

## Response `202`

Accepted; processing asynchronously.

- object
  - `analysis` Analysis
    - `completed_at` string, date-time, nullable
    - `credits_used` integer
    - `models` string[]
    - `recommendations` object[]: Generated recommendations; empty until POST /analysis/:uuid/recommendations succeeds.
      - `action` string
      - `priority` 'high' | 'medium' | 'low'
      - `reasoning` string
      - `target_keywords` string[]
      - `target_urls` string[]
    - `recommendations_generated_at` string, date-time, nullable
    - `response_count` integer
    - `scope` 'site' | 'customer_type' | 'persona' | 'questions'
    - `site_uuid` string
    - `started_at` string, date-time
    - `status` 'pending' | 'running' | 'completed' | 'failed'
    - `uuid` string
  - `estimated_credits` integer

## Other responses

- `401`: Missing, invalid, or revoked API key.
- `403`: Authenticated but lacks permission (e.g. botsee_disabled).
- `404`: The requested resource does not exist or is not accessible.
- `422`: Request body or parameters failed validation.
- `429`: Too many requests. Wait and retry per Retry-After header.

---

[API](https://skmtc.dev/botsee/apis/botsee-api.md) · [All operations](https://skmtc.dev/botsee/apis/botsee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/botsee/apis/botsee-api/revisions/f815b844e73b?raw)