Skip to main content
Glama

Check an async scrape job status

scrape_status

Check the state of an async scrape job (pending, running, done, or failed) and poll until completion, then fetch the page. Returns errors and usage details for done jobs.

Instructions

Look up the current lifecycle status of an async scrape job submitted via scrape_async. Returns the job state (pending, running, done, failed), with an error message when it failed and a response_meta.usage block (total_credit_cost and its parts, billed engine, resolved proxy tier) once it is done. A job whose page the site served ends done even when that page is a 404 or 503 — read page_status_code in the result. A job that could not reach the site at all ends failed (the error text is a general message, not the reason) and is not billed; retry later or check the url. Poll this until the status is done, then call scrape_result to fetch the page. If you registered a completion webhook on submit you can skip polling and react to the delivery instead. A job answers for 24 hours after it was submitted; after that this returns not_found, the same as for an unknown job id.

Input Schema

NameRequiredDescriptionDefault
job_idYesJob identifier returned by the `scrape_async` tool

Output Schema

NameRequiredDescriptionDefault
errorNoError message if the job ended in `failed`. A job whose page the site served, even a 404 page, ends `done`, not `failed`: read `page_status_code` in the `scrape_result`.
job_idYesThe job identifier
statusYesCurrent state of the job (pending, running, done, failed)
created_atYesISO-8601 UTC timestamp when the job was created
response_metaNoUsage accounting for the finished job. Present only once the job is `done`; `response_meta.usage` reports what the job cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.1.1
    • changedOutput schema / properties / response_meta / properties / usage / description
      Previous value: -"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost, plus the billed engine and the resolved proxy tier."
    • removedOutput schema / properties / response_meta / properties / usage / properties / credits
      Removed value: -{
      -  "deprecated": true,
      -  "description": "Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version.",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / response_meta / properties / usage / properties / screenshot_slices
      Removed value: -{
      -  "deprecated": true,
      -  "description": "Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version.",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • changedOutput schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_cost / description
      Previous value: -"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value."New value: +"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it."
    • changedOutput schema / properties / response_meta / properties / usage / properties / total_credit_cost / description
      Previous value: -"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value."New value: +"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it."
    • addedOutput schema / properties / response_meta / properties / usage / properties / zero_data_retention_credit_cost
      Added value: +{
      +  "description": "Credits added by zero data retention: 1 on a billed, fresh result, else 0. Older api versions do not send it.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
  2. Changed14 schema fields changedv1.1.0
    • changedOutput schema / properties / error / description
      Previous value: -"Error message if the job ended in `failed`"New value: +"Error message if the job ended in `failed`. A job whose page the site served, even a 404 page, ends `done`, not `failed`: read `page_status_code` in the `scrape_result`."
    • changedOutput schema / properties / response_meta / description
      Previous value: -"Usage accounting for the finished job. Present only once the job is `done`; `response_meta.usage` reports credits charged, the billed engine, the resolved proxy tier, and any screenshot-slice add-on."New value: +"Usage accounting for the finished job. Present only once the job is `done`; `response_meta.usage` reports what the job cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier."
    • changedOutput schema / properties / response_meta / properties / usage / description
      Previous value: -"Usage accounting for this request: credits charged, billed engine, resolved proxy tier, and screenshot-slice add-on."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."
    • addedOutput schema / properties / response_meta / properties / usage / properties / credits / deprecated
      Added value: +true
    • changedOutput schema / properties / response_meta / properties / usage / properties / credits / description
      Previous value: -"Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free."New value: +"Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version."
    • changedOutput schema / properties / response_meta / properties / usage / properties / engine / description
      Previous value: -"The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested."New value: +"The engine the request was billed at — \"http\", \"browser\", \"screenshot\", or \"cache\" (the result was served from cache). Reflects what was delivered, never what was requested."
    • addedOutput schema / properties / response_meta / properties / usage / properties / engine_credit_cost
      Added value: +{
      +  "description": "The engine base charged, before the proxy multiplier: 1 for \"http\", 3 for \"browser\", 5 for \"screenshot\", 0 for \"cache\". Also 0 when the page is not billed (see page_status_code). Older api versions do not send it.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / response_meta / properties / usage / properties / proxy / description
      Previous value: -"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`)."New value: +"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`). \"advanced\" multiplies the engine base by 5."
    • addedOutput schema / properties / response_meta / properties / usage / properties / proxy_multiplier
      Added value: +{
      +  "description": "The multiplier of the proxy tier the request ran on: 1 for \"basic\", 5 for \"advanced\". Always reported, even when the engine cost is 0. Older api versions do not send it.",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / response_meta / properties / usage / properties / screenshot_slices / deprecated
      Added value: +true
    • changedOutput schema / properties / response_meta / properties / usage / properties / screenshot_slices / description
      Previous value: -"Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant."New value: +"Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version."
    • addedOutput schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_cost
      Added value: +{
      +  "description": "The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / response_meta / properties / usage / properties / total_credit_cost
      Added value: +{
      +  "description": "Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedOutput schema / properties / response_meta / properties / usage / required
      Previous value: -[
      -  "credits",
      -  "engine",
      -  "proxy",
      -  "screenshot_slices"
      -]New value: +[
      +  "engine",
      +  "proxy"
      +]
  3. First observedv1.0.3

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and does so: it enumerates the four states, explains that a site-served 404/503 still ends `done` (read `page_status_code`), that unreachable-site failures end `failed` with a generic error and are unbilled, and that jobs expire to `not_found` after 24 hours. Billing and TTL behavior are disclosed rather than left to inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return shape, then the edge cases. Dense but every sentence carries distinct information; the state enumeration and expiry detail make it slightly longer than strictly necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still explains the meaningful return semantics (state values, error text, usage block, page_status_code) and the full job lifecycle, so an agent has everything needed to poll, interpret, and hand off to `scrape_result`.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single `job_id` parameter already documented as coming from `scrape_async`. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('look up the current lifecycle status of an async scrape job') and explicitly ties it to the sibling `scrape_async` that creates the job, so it is distinguishable from `scrape_result` and `scrape_async` without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing: poll this until status is `done`, then call `scrape_result`; if a completion webhook was registered on submit, skip polling entirely. It also states the retry path for `failed` jobs. Alternatives and exclusions are both named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.