Skip to main content
Glama

Follow a long-running job

get_job
Read-onlyIdempotent

Check on a crawl, run, batch, web search or agent run a tool handed back as a job, and return its result once finished. Call it when a tool answered with status 'running' and a job; repeating that tool is not needed. To stop a crawl, run, batch or agent run use cancel_job. For a project's stored pages use list_pages. Inputs: kind, id and project_id come from the 'job' object; a crawl_site crawl_id is a crawl's id. For a crawl, url reads one page in full, even mid-crawl, and cursor from the last answer reads the next window. Behaviour: it answers at once and never waits, so call it again every 10 to 30 seconds while the status is 'running', or every 30 to 60 for an agent run. A finished crawl answers as crawl_site does (up to 50 pages excerpted per window), a batch as scrape_urls, a search as search_web, an agent run as run_agent, a run with its record. A scraping search whose pages are still landing answers with its results and the job. A crawl expires a day after it started unless kept, then answers 404; an agent run is kept 7 days, then answers with status 'expired'. Read-only and free: it reads stored data and never fetches.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "kind": "<kind>",
      "id": "<id>"
    },
    "name": "get_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesThe job's id.
urlNoCrawls only: one page's URL from the crawl's index.
kindYes'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls), 'extract' (scrape_urls with full=true), 'search' (search_web) or 'agent' (run_agent or continue_agent).
cursorNoCrawls only: the cursor the previous answer returned.
project_idNoA run's project id; required for a run, ignored otherwise.

Output Schema

NameRequiredDescriptionDefault
idNoA run, a search or an agent run: its id.
jobNoWhile running: {kind, id, project_id} to call again with.
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
dataNoA finished agent run: its answer, JSON matching the schema or {text}; {partial} at credit_limit.
noteNoWhat to do next.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
indexNoA finished crawl or batch: every page as {url, title, words, status}.
pagesNoA finished crawl or batch: pages with excerpts.
stepsNoAn agent run: the steps it has taken.
budgetNoAn agent run: the most it may spend.
countsNoPages by outcome so far.
cursorNoA crawl with more pages: pass it back for the next window.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
noticeNoOnly when a limit, not the site, held pages back: one line saying what they needed and why (the plan, the stealth trial or the credits left). Tell the person; it comes first in the answer.
statusNo'running' while it goes on; otherwise the finished job's status; 'expired' for an agent run past its keep date. On an error, the HTTP status code.
noticesNoWith `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, `engine` on a search's and `outlook` {tier, likely, why} on a page's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself.
resultsNoA search: the ranked results, as search_web returns them, with page excerpts when it scraped.
sourcesNoA finished agent run: the pages its answer rests on, each {url, title, pageId}.
crawl_idNoA crawl: its id.
markdownNoWith url: that page's markdown, capped at 12,000 characters.
stopReasonNoA finished agent run: why it stopped early, e.g. credit_limit, step_limit or cancelled; empty when it finished on its own.
creditsUsedNoAn agent run: credits spent so far, pages and model tokens.
fieldSourcesNoA finished agent run: where each value of data came from, its path (e.g. 'plans[0].price') to {url, pageId}; left out first when the answer is too long.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / notices / description
      Previous value: -"With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, and `engine` on a search's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself."New value: +"With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, `engine` on a search's and `outlook` {tier, likely, why} on a page's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself."
  2. Changed2 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs), 'search' (search_web) or 'agent' (run_agent or continue_agent)."New value: +"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls), 'extract' (scrape_urls with full=true), 'search' (search_web) or 'agent' (run_agent or continue_agent)."
    • changedInput schema / properties / kind / enum
      Previous value: -[
      -  "crawl",
      -  "run",
      -  "batch",
      -  "search",
      -  "agent"
      -]New value: +[
      +  "crawl",
      +  "run",
      +  "batch",
      +  "extract",
      +  "search",
      +  "agent"
      +]
  3. Changed14 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (search_web)."New value: +"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs), 'search' (search_web) or 'agent' (run_agent or continue_agent)."
    • changedInput schema / properties / kind / enum
      Previous value: -[
      -  "crawl",
      -  "run",
      -  "batch",
      -  "search"
      -]New value: +[
      +  "crawl",
      +  "run",
      +  "batch",
      +  "search",
      +  "agent"
      +]
    • changedOutput schema / description
      Previous value: -"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search search_web's, a run the run record, and `url` one page in full."New value: +"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search search_web's, an agent run run_agent's, a run the run record, and `url` one page in full."
    • addedOutput schema / properties / budget
      Added value: +{
      +  "description": "An agent run: the most it may spend.",
      +  "title": "Budget"
      +}
    • addedOutput schema / properties / creditsUsed
      Added value: +{
      +  "description": "An agent run: credits spent so far, pages and model tokens.",
      +  "title": "Creditsused"
      +}
    • addedOutput schema / properties / data
      Added value: +{
      +  "description": "A finished agent run: its answer, JSON matching the schema or {text}; {partial} at credit_limit.",
      +  "title": "Data"
      +}
    • addedOutput schema / properties / fieldSources
      Added value: +{
      +  "description": "A finished agent run: where each value of data came from, its path (e.g. 'plans[0].price') to {url, pageId}; left out first when the answer is too long.",
      +  "title": "Fieldsources"
      +}
    • changedOutput schema / properties / id / description
      Previous value: -"A run or a search: its id."New value: +"A run, a search or an agent run: its id."
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "Only when a limit, not the site, held pages back: one line saying what they needed and why (the plan, the stealth trial or the credits left). Tell the person; it comes first in the answer.",
      +  "title": "Notice"
      +}
    • addedOutput schema / properties / notices
      Added value: +{
      +  "description": "With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, and `engine` on a search's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself.",
      +  "title": "Notices"
      +}
    • addedOutput schema / properties / sources
      Added value: +{
      +  "description": "A finished agent run: the pages its answer rests on, each {url, title, pageId}.",
      +  "title": "Sources"
      +}
    • changedOutput schema / properties / status / description
      Previous value: -"'running' while it goes on; otherwise the finished job's status. On an error, the HTTP status code."New value: +"'running' while it goes on; otherwise the finished job's status; 'expired' for an agent run past its keep date. On an error, the HTTP status code."
    • addedOutput schema / properties / steps
      Added value: +{
      +  "description": "An agent run: the steps it has taken.",
      +  "title": "Steps"
      +}
    • addedOutput schema / properties / stopReason
      Added value: +{
      +  "description": "A finished agent run: why it stopped early, e.g. credit_limit, step_limit or cancelled; empty when it finished on its own.",
      +  "title": "Stopreason"
      +}
  4. Changed3 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (web_search)."New value: +"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (search_web)."
    • changedOutput schema / description
      Previous value: -"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search web_search's, a run the run record, and `url` one page in full."New value: +"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search search_web's, a run the run record, and `url` one page in full."
    • changedOutput schema / properties / results / description
      Previous value: -"A search: the ranked results, as web_search returns them, with page excerpts when it scraped."New value: +"A search: the ranked results, as search_web returns them, with page excerpts when it scraped."
  5. Changed5 schema fields changed
    • changedInput schema / properties / kind / description
      Previous value: -"'crawl' (crawl_site), 'run' (start_run) or 'batch' (scrape_urls with several URLs)."New value: +"'crawl' (crawl_site), 'run' (start_run), 'batch' (scrape_urls with several URLs) or 'search' (web_search)."
    • changedInput schema / properties / kind / enum
      Previous value: -[
      -  "crawl",
      -  "run",
      -  "batch"
      -]New value: +[
      +  "crawl",
      +  "run",
      +  "batch",
      +  "search"
      +]
    • changedOutput schema / description
      Previous value: -"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na run the run record, and `url` one page in full."New value: +"A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na search web_search's, a run the run record, and `url` one page in full."
    • changedOutput schema / properties / id / description
      Previous value: -"A run: its id."New value: +"A run or a search: its id."
    • addedOutput schema / properties / results
      Added value: +{
      +  "description": "A search: the ranked results, as web_search returns them, with page excerpts when it scraped.",
      +  "title": "Results"
      +}
  6. Changed6 schema fields changed
    • changedInput schema / properties / cursor / description
      Previous value: -"Crawls only: the cursor a previous crawl answer returned, to read the next window of pages."New value: +"Crawls only: the cursor the previous answer returned."
    • changedInput schema / properties / id / description
      Previous value: -"The job's id, from that 'job' object, or a crawl_site answer's crawl_id."New value: +"The job's id."
    • changedInput schema / properties / kind / description
      Previous value: -"What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or 'batch' (scrape_urls); the 'job' object a tool returned names it."New value: +"'crawl' (crawl_site), 'run' (start_run) or 'batch' (scrape_urls with several URLs)."
    • changedInput schema / properties / project_id / description
      Previous value: -"Required for a run: the project it belongs to (the 'job' object carries it). Ignored for a crawl or a batch."New value: +"A run's project id; required for a run, ignored otherwise."
    • changedInput schema / properties / url / description
      Previous value: -"Crawls only: one page's URL from the crawl's index, to read that page in full."New value: +"Crawls only: one page's URL from the crawl's index."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "A job's state, or its result once finished: a crawl gives crawl_site's answer, a batch scrape_urls',\na run the run record, and `url` one page in full.",
      +  "properties": {
      +    "code": {
      +      "description": "Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.",
      +      "title": "Code"
      +    },
      +    "counts": {
      +      "description": "Pages by outcome so far.",
      +      "title": "Counts"
      +    },
      +    "crawl_id": {
      +      "description": "A crawl: its id.",
      +      "title": "Crawl Id"
      +    },
      +    "cursor": {
      +      "description": "A crawl with more pages: pass it back for the next window.",
      +      "title": "Cursor"
      +    },
      +    "detail": {
      +      "description": "Only on a failure: the API's own wording, when the error was rephrased.",
      +      "title": "Detail"
      +    },
      +    "error": {
      +      "description": "Only when the call failed: what went wrong, in words an assistant can act on.",
      +      "title": "Error"
      +    },
      +    "id": {
      +      "description": "A run: its id.",
      +      "title": "Id"
      +    },
      +    "index": {
      +      "description": "A finished crawl or batch: every page as {url, title, words, status}.",
      +      "title": "Index"
      +    },
      +    "job": {
      +      "description": "While running: {kind, id, project_id} to call again with.",
      +      "title": "Job"
      +    },
      +    "markdown": {
      +      "description": "With url: that page's markdown, capped at 12,000 characters.",
      +      "title": "Markdown"
      +    },
      +    "note": {
      +      "description": "What to do next.",
      +      "title": "Note"
      +    },
      +    "pages": {
      +      "description": "A finished crawl or batch: pages with excerpts.",
      +      "title": "Pages"
      +    },
      +    "status": {
      +      "description": "'running' while it goes on; otherwise the finished job's status. On an error, the HTTP status code.",
      +      "title": "Status"
      +    }
      +  },
      +  "title": "JobOut",
      +  "type": "object"
      +}
  7. Changed6 schema fields changed
    • addedInput schema / properties / cursor / description
      Added value: +"Crawls only: the cursor a previous crawl answer returned, to read the next window of pages."
    • addedInput schema / properties / id / description
      Added value: +"The job's id, from that 'job' object, or a crawl_site answer's crawl_id."
    • addedInput schema / properties / kind / description
      Added value: +"What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or 'batch' (scrape_urls); the 'job' object a tool returned names it."
    • addedInput schema / properties / kind / enum
      Added value: +[
      +  "crawl",
      +  "run",
      +  "batch"
      +]
    • addedInput schema / properties / project_id / description
      Added value: +"Required for a run: the project it belongs to (the 'job' object carries it). Ignored for a crawl or a batch."
    • addedInput schema / properties / url / description
      Added value: +"Crawls only: one page's URL from the crawl's index, to read that page in full."
  8. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world, and the description adds substantial context beyond them: it answers immediately and never blocks, recommended poll intervals per job type, and expiry behavior (crawl expires after a day then 404s, agent run kept 7 days then reports 'expired'). It also clarifies that it reads stored data and never fetches, and maps result shape to the originating tool.

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 purpose, then trigger, then inputs, then behavior, with no filler sentences despite the density. It is on the long side, but nearly every clause carries operational information the agent needs; slight tightening of the result-shape list would make it ideal.

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

Completeness3/5

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

Strong on lifecycle and polling, but the description omits what to do when a job status is neither 'running' nor finished (e.g. failed or cancelled), leaving a gap for a tool whose whole purpose is status resolution. An output schema exists, so not explaining return fields is acceptable, though the description partially duplicates that by listing result shapes.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description earns more by explaining provenance ('kind, id and project_id come from the job object') and a non-obvious mapping ('a crawl_site crawl_id is a crawl's id'). It also clarifies that url reads one page in full even mid-crawl and cursor advances the window, adding semantics beyond the schema's brief field notes.

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 ('check on a crawl, run, batch, web search or agent run... and return its result once finished') and enumerates exactly which job kinds it covers. It distinguishes itself from siblings by naming cancel_job for stopping and list_pages for stored pages, so an agent can route correctly without opening other schemas.

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 an explicit trigger condition ('call it when a tool answered with status running and a job; repeating that tool is not needed') plus explicit alternatives for adjacent intents (cancel_job to stop, list_pages for stored pages). It also supplies a concrete polling cadence, which is guidance an agent cannot infer elsewhere.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.