---
title: "Get batch status"
method: GET
path: "/v1/web/batch/{id}"
tags: ["Crawl & batch"]
---

# Get batch status

`GET /v1/web/batch/{id}`

## Request

- Base URL: `https://api.hydrafetch.com`
- URL: `https://api.hydrafetch.com/v1/web/batch/{id}`
- Auth: API key in header `X-API-Key`

Poll a batch for its progress and per-URL results.

## Path parameters

- `id` string, required

## Response `200`

- CrawlStatusEnvelopeDto
  - `data` CrawlStatusResponseDto, required
    - `id` string, required: The crawl or batch id.
    - `kind` 'crawl' | 'batch', required: Which kind of job this is.
    - `status` 'running' | 'completed' | 'failed' | 'cancelled', required: Overall job state.
    - `seedUrl` object, nullable, required: The starting URL, for a crawl.
    - `total` number, required: Total pages in this job.
    - `completed` number, required: Pages scraped so far.
    - `failed` number, required: Pages that failed.
    - `creditsUsed` number, required: Credits consumed so far. One per scraped page.
    - `pages` CrawlPageResultDto[], required: Per-page status and results.
      - `url` string, required: The page URL.
      - `requestedUrl` string: For a batch, the URL exactly as you sent it, present only when it differed from `url` after normalisation (a trailing slash or #fragment). A batch always returns one entry per URL you submitted, in order, including duplicates — so you can match results back to your input list positionally.
      - `status` 'queued' | 'running' | 'completed' | 'failed', required: State of this page.
      - `depth` number, required: How many links deep this page was from the start.
      - `discoveredVia` 'requested' | 'sitemap' | 'link', required: How this URL entered the job. `requested` is a URL you gave us, meaning the crawl seed or a batch entry. `sitemap` came from the site's sitemap, `link` from following a link on a page we had already fetched.
      - `error` object, nullable, required: Human-readable failure message. Set when this page failed.
      - `errorCode` object, nullable, required: Stable machine-readable failure code. Set when this page failed.
      - `retryable` object, nullable, required: When failed: true if it gave up after real retries (transient — safe to re-submit), false if a terminal failure.
      - `data` WebScrapeDataDto, required
        - `url` string, required: The URL you requested.
        - `finalUrl` string, required: The final URL after any redirects.
        - `redirected` boolean, required: Whether the origin redirected: true when `finalUrl` differs from the URL you requested. Explicit so a page with no redirect is distinguishable from one whose redirect was not tracked.
        - `status` number, required: HTTP status of the fetched page.
        - `cached` boolean, required: Whether this result was served from cache.
        - `warning` string: Set when the page was returned with a caveat (e.g. partial content).
        - `metadata` WebScrapeMetadataDto, required
          - `title` object, nullable, required: The page title.
          - `structure` 'markdown' | 'plain', required: Whether the content carries markdown structure (headings, lists, emphasis) or is plain prose. `plain` is not an error — the default extractor optimises for capturing every word and wins on listing and forum pages. If you need the structure, re-request with `preferStructure: true`.
          - `pageType` string, required: Coarse page classification (e.g. article, listing, forum, docs).
          - `wordCount` number, required: Word count of the extracted main content.
          - `description` object, nullable, required: The page's own description (meta description / og:description).
          - `language` object, nullable, required: The language the page declares.
          - `author` object, nullable, required: The declared author.
          - `siteName` object, nullable, required: The declared site name.
          - `publishedTime` object, nullable, required: When the page says it was published (ISO 8601).
          - `modifiedTime` object, nullable, required: When the page says it was last updated (ISO 8601).
          - `image` object, nullable, required: The page's lead image (og:image).
        - `usage` WebUsageDto
          - `creditsUsed` number, required: Credits this call consumed. Charged only on success.
          - `creditsRemaining` number, required: Credits left in your workspace's balance after this call.
          - `freshness` 'cache' | 'fresh', required: Whether the result was served from cache or freshly fetched.
        - `quality` WebQualityDto
          - `confidence` number, required: How trustworthy the extraction is, from 0 to 1. High when independent checks corroborate substantial content; near zero when the page yielded almost nothing.
          - `complete` boolean, required: Whether the result captured the bulk of the content available on the page. False when the result looks thin or truncated.
          - `blocked` boolean, required: Whether the page appeared to be behind a challenge or bot wall.
        - `markdown` string: Clean Markdown of the main content. Returned when `markdown` is requested.
        - `html` string: Cleaned main-content HTML. Returned when `html` is requested.
        - `rawHtml` string: The unmodified page HTML. Returned when `rawHtml` is requested.
        - `links` WebLinksDto
          - `internal` string[], required: Links pointing to the same site.
          - `external` string[], required: Links pointing to other sites.
        - `structured` WebStructuredDataDto
          - `entities` WebStructuredEntityDto[], required: The page's own structured data, normalised into one deduplicated list of typed entities.
            - `type` string, required: The schema.org type of the entity.
            - `source` 'json-ld' | 'microdata' | 'rdfa' | 'opengraph', required: Which structured-data syntax the entity came from.
            - `properties` object, required: The entity's properties, as published.
          - `jsonLd` object[], required: Raw JSON-LD blocks, as found on the page.
          - `microdata` object[], required: Raw microdata items.
          - `opengraph` object[], required: Raw OpenGraph/Twitter-card tags.
          - `rdfa` object[], required: Raw RDFa items.
          - `appState` string[], required: Names of embedded framework app-state blocks detected on the page.
        - `summary` string: A concise factual summary. Returned when `summary` is requested (LLM-backed).
        - `json` object: Schema-shaped JSON. Returned when `json` is requested (LLM-backed).

## Other responses

- `400`: The request body or query failed validation.
- `401`: The X-API-Key header is missing, malformed, or names a key that no longer exists.
- `402`: The workspace has no credits left for this request. Nothing was charged and nothing was fetched.
- `403`: The key is valid but the workspace may not make this request.
- `404`: No such job, or the id belongs to another workspace.
- `422`: The target site did not respond, or we could not read that page. This is a fact about that URL rather than a fault on our side, and retrying it will not change the answer. When details.retryAfterSeconds is present, asking again before then returns this same answer. Nothing was charged.
- `429`: The workspace exceeded its per-minute request limit. Read the RateLimit headers, or Retry-After on this response, and retry after the window resets.
- `500`: Unexpected server error. Nothing was charged.
- `503`: A dependency needed for the requested formats is unavailable. Safe to retry.

---

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