> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Crawl status

> Check a background crawl and read the finished pages.

## Pages

Poll until `status` is `completed`, `failed` or `cancelled`, then call `next` until it is gone. An answer holds up to 100 finished pages or 2 MB, and a page's URL is in `metadata.url`. See [Read the results](https://docs.stophy.dev/crawl/async.md).

`failed` counts the pages that could not be read. `errors` lists the failed pages in this answer, and `error` is set only when the whole job failed. [Crawl errors](https://docs.stophy.dev/api-reference/endpoint/crawl-errors.md) lists every failed page.

```bash cURL theme={null}
curl https://api.stophy.dev/v1/crawl/job_qqmWroHTkWk61kDjA32Q3g \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json 200 theme={null}
{
  "success": true,
  "data": [
    {
      "markdown": "# Welcome to Bun\n\n> Bun is an all-in-one toolkit for developing modern JavaScript/TypeScript applications.\n…",
      "metadata": {
        "title": "Welcome to Bun",
        "sourceURL": "https://bun.com/docs",
        "url": "https://bun.com/docs",
        "statusCode": 200,
        "contentType": "text/markdown",
        "cacheState": "miss",
        "costUsd": 0.001
      }
    }
  ],
  "status": "completed",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "costUsd": 0.002,
  "createdAt": "2026-11-17T17:49:57.354Z",
  "completedAt": "2026-11-17T17:50:00.027Z",
  "duration": 2.673,
  "expiresAt": "2026-11-18T17:49:57.354Z",
  "errors": []
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /v1/crawl/{id}
openapi: 3.1.0
info:
  title: Stophy API
  version: '1'
  description: >-
    Each operation shows its method and its input: a JSON object body, path and
    query parameters, or a file upload.


    Responses leave out empty values: null, empty strings, empty objects and
    empty nested lists are not sent.


    Text comes back whole. To get shorter responses, add
    ?maxTextLength=<characters> to the URL. Every text value longer than that is
    cut and ends with …. A screenshot is never cut, and a page whose text was
    cut has isTruncated set to true.


    The x-cost-usd response header is what the request cost in dollars. An
    operation's description gives its pricing units and add-ons. The OpenAPI
    fields x-cost-usd and x-cost-usd-max are list-price estimates, not receipts
    or spending limits. When a call starts a job, check the job result for its
    total cost.


    When a response has a cursor, send it back unchanged with the same input to
    get the next page. When it has a page, send the next page number.
servers:
  - url: https://api.stophy.dev
security:
  - apiKey: []
paths:
  /v1/crawl/{id}:
    get:
      summary: Check a background crawl and read the finished pages
      description: Costs $0 per 1,000 calls. Pages with cursor.
      operationId: crawlStatus
      parameters:
        - $ref: '#/components/parameters/MaxTextLength'
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: checkpoint
          in: query
          required: false
          schema:
            description: >-
              Send ck_start to start reading with checkpoints. Send the returned
              checkpoint here to resume, even when no more pages are ready.
            type: string
            pattern: ^(?:ck_(?:start|[A-Za-z0-9_-]{20,32}))$
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            description: The cursor from the previous response. Send it as is.
      responses:
        '200':
          description: The data, and what this call cost in dollars.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-cost-usd:
              $ref: '#/components/headers/CostUsd'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            x-cache:
              $ref: '#/components/headers/Cache'
            x-cache-age:
              $ref: '#/components/headers/CacheAge'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  success:
                    type: boolean
                    const: true
                  status:
                    type: string
                    enum:
                      - scraping
                      - completed
                      - failed
                      - cancelled
                  queuePosition:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  total:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  completed:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  failed:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  error:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                        timestamp:
                          type: string
                        url:
                          type: string
                        error:
                          type: string
                        code:
                          type: string
                        message:
                          type: string
                        retryable:
                          type: boolean
                        at:
                          type: string
                      required:
                        - retryable
                  creditsUsed:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  costUsd:
                    type: number
                  createdAt:
                    type: string
                  completedAt:
                    type: string
                  duration:
                    type: number
                  expiresAt:
                    type: string
                  next:
                    type: string
                  checkpoint:
                    type: string
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        markdown:
                          type: string
                        summary:
                          type: string
                        html:
                          type: string
                        rawHtml:
                          type: string
                        links:
                          type: array
                          items:
                            type: string
                        images:
                          type: array
                          items:
                            type: string
                        attributes:
                          type: array
                          items:
                            type: object
                            additionalProperties: false
                            properties:
                              selector:
                                type: string
                              attribute:
                                type: string
                              values:
                                type: array
                                items:
                                  type: string
                            required: []
                        screenshot:
                          type: string
                        json:
                          $ref: '#/components/schemas/crawlStatus.schema0'
                        highlights:
                          type: string
                        isTruncated:
                          type: boolean
                        nextOffset:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        changeTracking:
                          type: object
                          additionalProperties: false
                          properties:
                            previousScrapeAt:
                              type: string
                            changeStatus:
                              type: string
                              enum:
                                - new
                                - same
                                - changed
                            visibility:
                              type: string
                            diff:
                              type: string
                          required: []
                        branding:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties:
                            $ref: '#/components/schemas/crawlStatus.schema0'
                        actions:
                          type: object
                          additionalProperties: false
                          properties:
                            screenshots:
                              type: array
                              items:
                                type: string
                            scrapes:
                              type: array
                              items:
                                type: object
                                additionalProperties: false
                                properties:
                                  url:
                                    type: string
                                  html:
                                    type: string
                                required: []
                            javascriptReturns:
                              type: array
                              items:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  value:
                                    $ref: '#/components/schemas/crawlStatus.schema0'
                                required: []
                            pdfs:
                              type: array
                              items:
                                type: string
                          required: []
                        warning:
                          type: string
                        metadata:
                          type: object
                          additionalProperties: {}
                          description: >-
                            Facts about the page. Named page facts such as
                            ogTitle or keywords appear when the page has them,
                            and every meta tag also appears under its own name,
                            such as og:title.
                          properties:
                            title:
                              type: string
                            description:
                              type: string
                            language:
                              type: string
                            ogImage:
                              type: string
                            sourceURL:
                              type: string
                            url:
                              type: string
                            statusCode:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            contentType:
                              type: string
                            numPages:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            totalPages:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            cacheState:
                              type: string
                              enum:
                                - hit
                                - miss
                                - stale
                            cachedAt:
                              type: string
                            scrapeId:
                              type: string
                            creditsUsed:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            costUsd:
                              type: number
                          required:
                            - statusCode
                      required:
                        - isTruncated
                        - metadata
                required:
                  - success
                  - status
                  - total
                  - completed
                  - failed
                  - errors
                  - creditsUsed
                  - costUsd
                  - data
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
components:
  parameters:
    MaxTextLength:
      name: maxTextLength
      in: query
      required: false
      description: >-
        Cut every text value in the response to this many characters. A value
        that was cut ends with …, and a page whose text was cut has isTruncated
        set to true. A screenshot is never cut. Leave it out to get the full
        text.
      schema:
        type: integer
        minimum: 1
  headers:
    RequestId:
      description: The request id. Quote it when you report a problem.
      schema:
        type: string
    CreditsUsed:
      description: >-
        Older header: what this call cost, as whole steps of $0.002. Use
        x-cost-usd.
      schema:
        type: integer
    CostUsd:
      description: What this call cost, in dollars.
      schema:
        type: string
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix time in seconds when the current window resets.
      schema:
        type: integer
    Cache:
      description: hit if this result came from the cache, miss if it was fetched live.
      schema:
        type: string
    CacheAge:
      description: Seconds since the returned result was written to the cache.
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    crawlStatus.schema0:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/crawlStatus.schema0'
        - type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/crawlStatus.schema0'
    Error:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          const: false
        error:
          type: string
          description: What went wrong and what to do next.
        code:
          type: string
          enum:
            - apiKeyRequired
            - busy
            - checkRunning
            - cliSessionCompleted
            - cliSessionExists
            - cliSessionNotFound
            - forbidden
            - freeLimit
            - insufficientCredits
            - internalError
            - inviteClaimed
            - inviteDisabled
            - inviteExpired
            - inviteUsedUp
            - invalidCliSession
            - invalidCliVerifier
            - invalidRequest
            - jobFinished
            - methodNotAllowed
            - notFound
            - payloadTooLarge
            - profileBusy
            - profileTooLarge
            - prohibitedPermission
            - promptInjectionDetected
            - rateLimited
            - sourceChanged
            - sourceRefused
            - siteNotRead
            - sourceTimeout
            - sourceUnavailable
            - unauthorized
            - unsupportedMediaType
        retryable:
          type: boolean
          description: true when trying again can help.
        retryAfterSeconds:
          type: integer
        requestId:
          type: string
        requiredCredits:
          type: number
          description: >-
            Older field: the most the call can cost, in $0.002 steps. Sent when
            the balance is too low.
        availableCredits:
          type: number
          description: 'Older field: the balance in $0.002 steps. Sent with requiredCredits.'
        requiredUsd:
          type: number
          description: >-
            The most the call can cost, in dollars. Sent when the balance is too
            low.
        availableUsd:
          type: number
          description: What is left on the account, in dollars. Sent with requiredUsd.
        billingUrl:
          type: string
          description: Where to add money. Sent with requiredUsd.
        signupUrl:
          type: string
          const: https://stophy.dev/signup
          description: >-
            Where a person gets a key. Sent with apiKeyRequired, freeLimit and
            an invalid key.
        signup:
          type: string
          const: POST https://api.stophy.dev/v1/signup
          description: >-
            The call that gets an agent a key with no human. Sent next to
            signupUrl.
  responses:
    Error:
      description: The request failed. Retry-After says when trying again can help.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.