---
title: "One crawl's status, progress and what it left out"
method: GET
path: "/v1/crawls/{crawl_id}"
tags: ["crawls"]
---

# One crawl's status, progress and what it left out

`GET /v1/crawls/{crawl_id}`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/crawls/{crawl_id}`
- Auth: HTTP bearer

One crawl: its status, pages read so far and `coverage`, what it did not read and why. Poll it after crawls_start until `crawl.terminal` is true; there is no estimated finish time. `partial_budget` and `partial_blocked` mean the crawl did not read the whole site, and a crawl that read 0 pages could not read the site: neither is a healthy site. `coverage` null means not measured (an old crawl, or one that never started), never that nothing was left out. Quote the crawl's figures as a claim about what it read. Next: when it is terminal, read what it found with issues_list.

## Path parameters

- `crawl_id` string, required: The crawl id (cr_...) crawls_start answered, or a site's current crawl.

## Response `200`

One crawl's status, progress and what it left out

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `crawl` object, required: The crawl run.
    - `id` string, required: The crawl id.
    - `site_id` string, required: The canonical id of the site crawled.
    - `crawl_seq` integer, required: The site's crawl number.
    - `status` 'queued' | 'leased' | 'running' | 'finalizing' | 'complete' | 'complete_with_exclusions' | 'partial_budget' | 'partial_blocked' | 'failed_infrastructure' | 'cancelled', required: The honest outcome, not a boolean: `complete`, `complete_with_exclusions`, `partial_budget`, `partial_blocked`, `failed_infrastructure`, `cancelled`, or a live state.
    - `terminal` boolean, required: True once the status will not change.
    - `source` 'scheduled' | 'dashboard' | 'mcp' | 'api' | 'recheck' | 'first_crawl' | 'admin', required: Who started it: `mcp` and `api` are agents.
    - `pages_crawled` integer, required: Pages the crawl has read so far.
    - `bytes_downloaded` integer, required: Bytes the crawl has downloaded so far.
    - `error_code` string, nullable, required: Why the crawl failed, when it did; null otherwise.
    - `started_at` string, nullable, required: When a crawler started it (ISO 8601); null while it is queued.
    - `completed_at` string, nullable, required: When it ended (ISO 8601); null until it has.
    - `dashboard_url` string, required: The site's page in Frontshelf to hand your human (app-relative).
  - `coverage` object, nullable, required: What the crawl did not read, and why. Null means not measured, never nothing left out.
    - `left_out_by_reason` object, required: URLs the crawl admitted and did not read, by reason (excluded, max_urls, a fetch failure, ...).
    - `left_out_total` integer, required: The sum of `left_out_by_reason`.
    - `limit_reached` boolean, required: True when the crawl stopped at its page limit.
    - `pages_admitted` integer, required
    - `resources_admitted` integer, required
    - `external_total` integer, required
    - `external_admitted` integer, required
    - `by_kind` object, required
      - `page` object, required
        - `queued` integer, required
        - `leased` integer, required
        - `done` integer, required
        - `failed` integer, required
        - `skipped` integer, required
      - `resource` object, required
        - `queued` integer, required
        - `leased` integer, required
        - `done` integer, required
        - `failed` integer, required
        - `skipped` integer, required
      - `external` object, required
        - `queued` integer, required
        - `leased` integer, required
        - `done` integer, required
        - `failed` integer, required
        - `skipped` integer, required

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `404`: CRAWL_NOT_FOUND
- `409`: AGENT_STOPPED
- `503`: DEPENDENCY_UNAVAILABLE

---

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