---
title: "Read one scan and its accumulated list of places"
method: GET
path: "/competitor-scans/{id}"
tags: ["Competitor scans"]
---

# Read one scan and its accumulated list of places

`GET /competitor-scans/{id}`

## Request

- Base URL: `https://api.epovest.com/v1`
- URL: `https://api.epovest.com/v1/competitor-scans/{id}`
- Auth: HTTP bearer

Every place holds `subjects`, the number of the basket corroborated there, its `reach` (the
way in), the `ai_authority` of the domain, its exact `pages`, and `client_present`, which
says whether the account already recorded a corroboration there. The list ACCUMULATES over
every check, deduplicated by URL, so `seen_in_checks` counts checks and never citations.
`controlled` is what each company publishes on its own site, and `rivals` the competitive set
the engine names. To act on a place, add a quest with its URL.

## Response `200`

The scan, and its report once it has results.

- object
  - `competitor_scan` CompetitorScan, required
    - `id` string, uuid, required
    - `project_id` string, uuid, required
    - `project` string, required
    - `title` string, required
    - `engine` 'chatgpt' | 'claude' | 'gemini' | 'perplexity' | 'mistral' | 'grok', required: The AI assistants the questions are asked to.
    - `language` string, required
    - `country` string, nullable, required
    - `category` string, nullable, required
    - `usage` string, nullable, required
    - `status` 'draft' | 'measuring' | 'ready' | 'failed', required
    - `rescan_cadence` 'weekly' | 'monthly' | 'null', nullable, required
    - `checks_completed` integer, required
    - `estimated_cost_minor` integer, required: What arming the scan spends, in minor units of the wallet currency.
    - `subjects` object[], required
      - `name` string
      - `website` string
      - `domain` string
    - `questions` object[], required
      - `id` string, uuid
      - `subject` string
      - `family` 'about' | 'compared'
      - `template` 'about_reputation' | 'about_price' | 'about_customers' | 'compared_alternatives': Which of the four questions each company gets.
      - `text` string
    - `created_at` string, date-time, required
    - `launched_at` string, date-time, nullable, required
    - `author` string, nullable, required
  - `report` CompetitorScanReport, required
    - `checks` integer, required
    - `measured_from` string, date, nullable, required
    - `measured_to` string, date, nullable, required
    - `answers_collected` integer, required
    - `answers_with_sources` integer, required
    - `places` object[], required: The domains the engine cited while answering about the basket, ranked by how many of it each place covers.
      - `domain` string
      - `reach` 'self_serve' | 'participate' | 'ask' | 'registry': The way in: `self_serve` to open your own page, `participate` for a forum or a community, `ask` for a third-party editorial site, `registry` when the page follows an official filing.
      - `subjects` integer: How many of the basket are corroborated there.
      - `subject_names` string[]
      - `ai_authority` integer, nullable
      - `source_id` string, uuid, nullable
      - `citations` integer
      - `reads` integer
      - `best_position` integer, nullable
      - `seen_in_checks` integer: How many checks brought the place back. The list accumulates over every check, deduplicated by URL.
      - `first_seen_on` string, date, nullable
      - `last_seen_on` string, date, nullable
      - `client_present` boolean: Whether the account already recorded a corroboration there.
      - `client_owned` boolean
      - `pages` CompetitorPlacePage[]
        - `url` string
        - `cited` integer
        - `read` integer
        - `best_position` integer, nullable
        - `seen_in_checks` integer
        - `first_seen_on` string, date, nullable
        - `last_seen_on` string, date, nullable
    - `controlled` object[], required: What each company publishes on its own site.
      - `subject` string
      - `domain` string
      - `page_count` integer
      - `citations` integer
      - `pages` CompetitorPlacePage[]
        - `url` string
        - `cited` integer
        - `read` integer
        - `best_position` integer, nullable
        - `seen_in_checks` integer
        - `first_seen_on` string, date, nullable
        - `last_seen_on` string, date, nullable
    - `rivals` object[], required: The competitive set the engine names.
      - `domain` string
      - `subjects` integer
      - `subject_names` string[]

## Other responses

- `401`: `unauthenticated`: missing, unknown or revoked key.
- `403`: `insufficient_scope`: the credential may not do this, either because the key lacks the scope, or, on a one-click connection, because the person lacks the role the action needs (manager, or owner to start, pause and top up). On that path, read it as "this person may not do this" and tell them which role the action needs.
- `404`: `not_found`: unknown for this account.
- `429`: `rate_limited`: 120 requests per minute per credential, sliding window. Retry after `Retry-After` seconds.

---

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