Mercator documentation

Mercator gives agents one interface to:

• Find tools for an open-ended workflow.
• Quote an immutable plan of one or more tool calls.
• Pay for and run the plan as one durable job.

Downstream services remain independently operated and use open payment protocols such as MPP and x402.

AgentIntent + budget

Mercator

01Search the web

02Enrich records

03Compose result

Downstream services

ExaWeb search

ParallelWeb research

OpenAIModel inference

Choose a path

Installation

1. Run the installer in your computer's terminal:

   curl -fsSL https://mercator.sh/install.sh | sh

2. Select the installed agents you want to connect.

3. Complete authorization in your agent, then run your first job.

• Claude Desktop, Claude web, or ChatGPT: use Agent setup.
• Updates and installer options: see the CLI reference.
• New wallet session: sign in and approve payment permission in one Tempo Wallet approval.
• Existing wallet session: approve access for the same account wallet.

Run your first job

1. Authorize Mercator in your agent and fund your wallet in Account.

2. Give your agent this prompt:

   Use Mercator to find NVIDIA's latest 10-Q and 8-K via SEC submissions. Return official links,
   dates, and one-sentence summaries.

3. Expect both filings, dates, official links, and summaries.

4. If execution is still pending, keep the job ID and ask the agent to resume polling it.

• Search, service inspection, and quotes are free.
• Paid execution uses the wallet limits approved during authorization; an explicit prompt budget is an additional limit.
• Native MPP clients such as Hermes need a configured payment wallet and quote approval or an explicit spending budget.
• A pending job does not need another purchase.

Example prompts

Ask for get_suggested_queries to retrieve the same examples shown under Try Mercator after setup.

Agent setup

Choose your app below, or use the standalone setup checklist.

Local agents

Run the installer in the terminal where your agent runs:

curl -fsSL https://mercator.sh/install.sh | sh

To configure just one client during installation, pass its ID after sh -s --:

curl -fsSL https://mercator.sh/install.sh | sh -s -- --client cursor

Activate after installation

1. Load the installed configuration using your client's action below.
2. Complete the client's OAuth flow. Mercator requests mercator:tools for /mcp/auth.
3. Call search_services and get_connection_status in that client.

• Setup lists each client under Client readiness with its activation and authorization steps. A written registration stays "authorization pending" until you authorize in the client.
• mercator refresh updates managed files but does not restart clients.
• mercator doctor verifies the separate CLI connection.

For immediate terminal access, use the CLI MCP client.

mercator setup --client claude

mercator setup --client codex

mercator setup --client cursor

mercator setup --client vscode

mercator setup --client gemini

mercator setup --client cline

mercator setup --client continue

mercator setup --client windsurf

mercator setup --client grok

mercator setup --client hermes

mercator setup --client kiro

mercator setup --client lmstudio

mercator setup --client muse

mercator setup --client openclaw

mercator setup --client zed

Verify the connection

In the client you connected, ask:

Use Mercator to search for web research services, then check my connection status.
Do not create a paid job.

• Confirm the agent can call search_services and get_connection_status; both checks are free. The status response includes the wallet address and public access-key address.
• For a REST client, call GET /v1/connection/status with its /mcp/auth OAuth bearer token. Missing, invalid, or revoked tokens return 401; the response is never cached.
• Follow any returned authorization or funding steps. Registration, a browser account login, or an HTTP 401 challenge alone does not prove the client's connection is ready.
• Hosted OAuth: choose wallet limits and expiry during authorization. Zero limits allow connecting without spending authority; a successful connection does not imply paid readiness.
• Hermes/native MPP: get_connection_status reports mcp_challenge without wallet balances. Check the native payment plugin and wallet separately; this response does not verify spending readiness.
• Keep each client's authorization in that client. CLI login and mercator doctor cannot verify credentials owned by another agent host.

Payments

Mercator sponsors up to 8,000,000 declared gas per Tempo charge, including first-use access-key installation. This sponsor policy is separate from Tempo’s transaction gas limit; fee-price and total-fee ceilings still apply.

For LLM calls, follow the service’s input schema: include an output token limit and keep streaming/background execution disabled. The proxy RPC service accepts read-only methods.

Pricing and spending limits

• Pass the quote token and exact quote total into submission; Mercator charges that quote until validUntil. Requote expired quotes.
• Hosted OAuth limits and any explicit user budget cap spending.
• Native MPP and local wallets require quote approval or a sufficient explicit budget, and a new quote after a price change.
• Never paste or send private keys; wallet tooling handles signing and authorization.

Mercator supports MPP with two payment methods:

• Tempo: Mercator displays prices denominated in USDC.e, but clients also can pay for Mercator services in MACH credits or through a supported pathUSD auto-swap.
• Stripe: Pay in USD with a shared payment token (SPT). Configured payments require whole-cent totals of at least $0.01.

Funding and MACH

MACH is a credit that can be used on Tempo for paying approved merchants, including Mercator.

1. Open Account, or ask your agent to call fund_wallet.
2. Confirm the authenticated wallet address.
3. Choose an amount and complete checkout; the connected wallet uses MACH for subsequent paid jobs.

Claim a grant

Claim five free MACH with GitHub or X on your Mercator account page or through the CLI:

mercator account claim github

mercator account claim x

Failed-job refunds

• A failed provider purchase is billable only when the provider caused it: an HTTP failure, a terminal failure status, or an incomplete result.
• Purchases wasted by Mercator, such as output limits or completion timeouts, are refunded.
• Invalid Monid sign-in challenges during result retrieval are nonbillable. Failures report providerStatus: 402, providerErrorKind: "authentication", and retryable: false; use the error_id for support rather than paying to repeat the job.
• Execution completion and refund settlement are separate; inspect usage.refundStatus and continue polling pending settlement. For Tempo payments, an uncertain provider call is provisionally billed and the rest is refunded automatically. When a provider refuses Mercator's payment with a fresh challenge, Mercator confirms on chain within about 30 seconds that nothing was paid, then retries the node or refunds its share when the job finishes. If usage.refundStatus is failed and usage.refundError is reconciliation_required, the Tempo refund is held: contact the operator with the job ID. Polling or resubmitting does not release the hold. The operator must reconcile provider settlement and any prior issuance before releasing funds.

CLI reference

Install, configure, and call Mercator from your terminal.

• The installer downloads a checksum-verified standalone executable; Node.js and Bun are not required.
• It updates the active shell's PATH profile when needed.
• A failed reinstall keeps the existing executable.

Configuration

Pass setup arguments after sh -s --:

curl -fsSL https://mercator.sh/install.sh | sh -s -- --client codex

• Codex/ChatGPT desktop: Installs one local plugin by default. ChatGPT web uses the separate developer-mode app setup.
• Claude Code and Grok CLI: Registers the public tempoxyz/plugins marketplace and installs its Mercator plugin.
• No detected client: Installs the local desktop plugin when enabled. Install a supported client and rerun setup, or use mercator setup --manual for other MCP clients.
• Cloud/team marketplaces: Managed by the host.

CLI commands

Use the CLI as an MCP client

1. Run mercator login and complete browser authorization.
2. Inspect live tools with mercator tools.
3. Call a tool with mercator call:

mercator login
mercator tools
mercator call get_connection_status
mercator call search_services \
  --input '{
  "query": "web research"
}'
mercator doctor

• mercator setup reuses existing CLI credentials to check discovery and spending capacity. Interactive mercator setup --login signs in when needed.
• The CLI connection is named mercator cli; agent clients authorize separately.
• Setup authorizes the CLI only with --login; CLI login creates a separate access key that can spend.
• --yes, non-interactive setup, and mercator refresh never launch login.
• Cancelled login leaves integrations installed; retry with mercator setup --login.
• Choose wallet limits in the browser authorization flow. Login and doctor create no paid jobs.
• If approval happens on another device, copy the completion link and paste it into the waiting mercator login prompt. The CLI also accepts the code from that link.
• tools returns current tool descriptions and input schemas. call accepts a JSON object and returns the MCP result; tool errors exit nonzero. Paid tools use the connection's approved limits.
• Credentials stay in endpoint-scoped, owner-only files under ~/.local/share/mercator/oauth/. Expiring bearers refresh automatically. Other agent clients retain their own authorization.
• The Tempo access key remains valid until revoked by default. Revoke the connection in Account to disable OAuth first, then ask Tempo Wallet to revoke the on-chain key. For a key that has not yet been published, Account returns its signed public authorization so Wallet can authorize and revoke it in one transaction.
• mercator logout removes local CLI credentials. Revoke mercator cli in Account to revoke its wallet access.

Setup options

The bootstrap installer accepts these environment overrides:

Install the plugin from the Tempo marketplace

The installer bootstraps the Mercator plugin for detected supported clients. To install it directly, add the public Tempo marketplace and select the mercator@tempo plugin:

codex plugin marketplace add tempoxyz/plugins --ref main
codex plugin add mercator@tempo

claude plugin marketplace add tempoxyz/plugins
claude plugin install mercator@tempo --scope user

grok plugin marketplace add tempoxyz/plugins
grok plugin install mercator@tempo

Manual installation

Merge configuration examples into the existing file; preserve other servers and settings.

1. Run mercator setup --manual.
2. Add https://mercator.sh/mcp/auth using Streamable HTTP.
3. Complete OAuth in the client; use the registration instructions if it requires a client ID.
4. Verify with search_services and get_connection_status there.

• Registration or a 401 challenge does not prove payment readiness.
• mercator doctor cannot read client-managed credentials.

You can register the remote MCP endpoint directly in a supported harness:

• For harnesses with tool search, such as Claude Code and Codex, append ?tools=all to the URL to list every catalog service as its own tool. Omit it for clients that load every tool into context.

codex mcp add mercator --url https://mercator.sh/mcp/auth --oauth-client-registration dcr

claude mcp add --scope user --transport http mercator https://mercator.sh/mcp/auth

gemini mcp add mercator https://mercator.sh/mcp/auth --transport http --scope user

code --add-mcp '{"name":"mercator","type":"http","url":"https://mercator.sh/mcp/auth"}'

openclaw mcp set mercator '{"url":"https://mercator.sh/mcp/auth","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login mercator

hermes mcp add mercator --url https://mercator.sh/mcp

{"mcpServers":{"mercator":{"url":"https://mercator.sh/mcp/auth"}}}

{"mcpServers":{"mercator":{"url":"https://mercator.sh/mcp/auth"}}}

mercator setup --client muse --no-plugin --no-agents
muse mcp login mercator

{"context_servers":{"mercator":{"url":"https://mercator.sh/mcp/auth"}}}

Manual registration saves the server configuration. Complete authorization and verify the connection in that client. OAuth-capable clients open Account when authorization is required. Run mercator account to manage wallet access, limits, funding, and revocation.

Mercator for service owners

Request discovery for services using supported open payment protocols such as MPP and x402.

Email mercator@tempo.xyz with:

• Service URL.
• Documentation or OpenAPI URL.
• Supported payment protocol.
• Short capability description.

Mercator ingests reviewed catalogs and endpoint metadata.

Troubleshooting

Contact support

• Email mercator@tempo.xyz, or use Report a bug.
• Include the x-mercator-request-id response header or MCP error.request_id, and any failure error_id; neither grants access to results.
• Include a known job ID only when authorizing maintainers to access its results.
• Exclude secrets, credentials, payment material, personal data, and raw inputs or outputs.
• Use Review a job for workflow and service-quality feedback.

API reference

OpenAPI specification

Choose REST or MCP

Authentication

Run a REST workflow

1. Search services for the complete outcome.

2. Describe the endpoint if you need its input schema.

3. Save the exact service, method, path, and schema-valid input in plan.json:

   {
     "nodes": [{
       "id": "filing",
       "serviceId": "{{SERVICE_ID}}",
       "method": "{{METHOD}}",
       "path": "{{PATH}}",
       "input": {"query": "latest official NVIDIA SEC filing"},
       "dependsOn": []
     }]
   }

4. Quote the plan for free and check the total against your budget.

5. Create a job with the unchanged plan, the quote's quoteToken and totalAmount as approvedTotal, and a persisted idempotency key.

6. Get the job until it reaches a terminal status.

7. Read selected node results if you only need part of the output.

• The input above is a template: replace it with the endpoint's actual fields.
• New jobs may acquire an optional title asynchronously, summarizing requested work. Job history and job reads return it when available; execution does not wait for it, and older jobs are not backfilled. Titles can also appear in shared receipt metadata.
• MCP follows the same sequence: search_services → describe_service when needed → quote_plan → create_job → get_job.
• Pass the search response's id unchanged to quote and submission when available.
• Keep the returned job ID; resume polling after a disconnect.

Call specific services

Skip search and call endpoints you already chose, such as fal, Exa, or Parallel, with your existing Mercator connection and balance.

1. Run mercator login once, or connect any MCP client to https://mercator.sh/mcp/auth. No provider API keys are needed.

2. Get the endpoint's input schema with describe_service:

   mercator call describe_service \
     --input '{"service_id": "fal", "method": "POST", "path": "/minimax/h3-max/text-to-video"}'

3. Put one node per endpoint in a plan, using the exact serviceId, method, and path:

   mercator call quote_plan --input '{
     "plan": {"nodes": [{
       "id": "video",
       "serviceId": "fal",
       "method": "POST",
       "path": "/minimax/h3-max/text-to-video",
       "input": {"prompt": "A cinematic ocean wave at sunrise"},
       "dependsOn": []
     }]}
   }'

4. Submit the unchanged plan with the quoted quoteToken and totalAmount and a new idempotency key:

   mercator call create_job --input '{
     "approved_total": "{{QUOTED_TOTAL}}",
     "quote_token": "{{QUOTE_TOKEN}}",
     "idempotency_key": "ocean-video-001",
     "plan": {"nodes": [{
       "id": "video",
       "serviceId": "fal",
       "method": "POST",
       "path": "/minimax/h3-max/text-to-video",
       "input": {"prompt": "A cinematic ocean wave at sunrise"},
       "dependsOn": []
     }]}
   }'

5. Poll get_job with the returned job_id until the job is terminal.

• Hosted OAuth limits authorize the charge; no per-job approval or provider account is needed.
• describe_service returns the authoritative inputSchema; the inputs below are minimal examples.
• Writes that act outside Mercator, such as orders, uploads, calls, and email, include effects (kind, reversible, cleanup, retention) in describe_service, and quote_plan lists them in next_action. Confirm them with the user before submitting; Mercator cannot undo them.
• To search only providers you chose, pass service_ids with service_mode: "require" to search_services. Use "prefer" to rank them first while keeping fallbacks.

Common endpoints

Combine services in one job

Chain several chosen services in one plan and pay once. This plan searches with Exa, then reads every result URL:

{
  "nodes": [
    {
      "id": "find",
      "serviceId": "exa",
      "method": "POST",
      "path": "/search",
      "input": {"query": "Series A fintech startups in Berlin"},
      "dependsOn": []
    },
    {
      "id": "read",
      "serviceId": "exa",
      "method": "POST",
      "path": "/contents",
      "input": {"ids": {"$map": {"from": "flow://find/output#/results", "path": "/url"}}},
      "dependsOn": ["find"]
    }
  ]
}

• Nodes without dependencies run concurrently, at most 3 at once per service; a plan has at most 10 nodes.
• flow://node_id/output passes an earlier output; append #/json/pointer to select a field.
• Check the upstream output shape with describe_service before mapping fields.

Search services

• Start with the complete task; use the default static resolution for fast discovery.
• Use require for mandatory providers or prefer to retain relevant alternatives.
• Follow the returned nextTool; inspect missing inputs before quoting.

mercator call search_services \
  --input '{
  "query": "find the latest official NVIDIA SEC filing",
  "limit": 5
}'

{
  "id": "123e4567-e89b-42d3-a456-426614174000",
  "resolution": "static",
  "endpoints": [{
    "rank": 1,
    "serviceId": "parallel",
    "method": "POST",
    "path": "/api/search",
    "requiredArguments": ["query"],
    "nextTool": "describe_service"
  }],
  "nextTool": "describe_service"
}

Constraints

• Free; search does not execute provider work.
• Live resolution attempts bounded probes; indeterminate endpoints can remain in results.
• Catalog examples describe accepted input; do not submit them as the user's request.

Errors and recovery

Describe a service

• Use after search when an endpoint needs its complete input schema, examples, or payment offers.
• Select one endpoint with both method and path, especially for large services.

mercator call describe_service \
  --input '{
  "service_id": "parallel",
  "method": "POST",
  "path": "/api/search"
}'

{
  "service": {
    "id": "parallel",
    "endpoints": [{
      "method": "POST",
      "path": "/api/search",
      "inputSchema": {"type": "object", "required": ["query"]}
    }]
  }
}

Constraints

• Free; inspection does not purchase provider results.
• Copy the exact cataloged service, method, and path into the plan.

Errors and recovery

• A missing or stale service or endpoint requires a new search.
• If the service is too large to describe, supply both endpoint selectors.

Suggested queries

• Use when the user wants ideas; present suggestions before executing one.

mercator call get_suggested_queries

{
  "queries": [{
    "id": "escape-the-fog",
    "title": "Escape the fog",
    "complexity": "moderate",
    "prompt": "Compare tomorrow's SF, Half Moon Bay and Livermore forecasts; map the sunniest trip from the Ferry Building with two food stops."
  }]
}

Constraints

• No parameters; free and read-only.
• Listing a prompt does not authorize a paid job.

List recipes

• Use when the outcome matches a curated workflow: a web research brief, a three-place forecast comparison, or a token market snapshot.
• Each recipe lists typed parameters, defaults, and its plan template; the matching use case shows the workflow.

mercator call list_recipes

{
  "recipes": [{
    "id": "web-research-brief",
    "title": "Web research brief",
    "useCase": "deep-research",
    "parameters": [
      {"name": "topic", "type": "string", "maxLength": 300, "example": "Series A fintech startups in Berlin"},
      {"name": "result_count", "type": "integer", "minimum": 1, "maximum": 10, "default": 5}
    ],
    "plan": {"nodes": [
      {"id": "search", "serviceId": "exa", "method": "POST", "path": "/search", "input": {"query": {"$param": "topic"}, "numResults": {"$param": "result_count"}}, "dependsOn": []},
      {"id": "read", "serviceId": "exa", "method": "POST", "path": "/contents", "input": {"ids": {"$map": {"from": "flow://search/output#/results", "path": "/url"}}}, "dependsOn": ["search"]}
    ]}
  }]
}

Constraints

• No parameters; free and read-only.
• {"$param": "name"} marks a parameter value; {"$template": "text {name}"} marks parameters interpolated into a string. Build the plan instead of filling templates by hand.

Build a recipe plan

• Turn a recipe and its parameters into a plan, then quote it and create a job unchanged.
• Ask for required parameters; omitted optional parameters use their defaults.

mercator call build_recipe_plan \
  --input '{
  "recipe_id": "web-research-brief",
  "parameters": {"topic": "Series A fintech startups in Berlin"}
}'

{
  "recipeId": "web-research-brief",
  "parameters": {"topic": "Series A fintech startups in Berlin", "result_count": 5},
  "plan": {"nodes": [
    {"id": "search", "serviceId": "exa", "method": "POST", "path": "/search", "input": {"query": "Series A fintech startups in Berlin", "numResults": 5}, "dependsOn": []},
    {"id": "read", "serviceId": "exa", "method": "POST", "path": "/contents", "input": {"ids": {"$map": {"from": "flow://search/output#/results", "path": "/url"}}, "text": {"maxCharacters": 4000}}, "dependsOn": ["search"]}
  ]}
}

Constraints

• Free and deterministic; building a plan does not call providers, pay, or create a job.
• Parameter values are literal: strings cannot be flow:// references.
• The quote and job follow the ordinary payment, idempotency, and retry rules.

Errors and recovery

Quote a plan

• Quote the complete plan after filling required inputs.
• Keep the plan unchanged between quote and submission.
• Submit quoteToken unchanged as MCP quote_token or REST quoteToken.
• Use totalAmount as MCP approved_total, REST approvedTotal, or the local CLI's --max-spend value.

{
  "plan": {
    "nodes": [{
      "id": "filing",
      "serviceId": "{{SERVICE_ID}}",
      "method": "{{METHOD}}",
      "path": "{{PATH}}",
      "input": {"query": "latest official NVIDIA SEC filing"},
      "dependsOn": []
    }]
  }
}

{
  "advisory": true,
  "currency": "USD",
  "totalAmount": "0.02",
  "dynamic": false,
  "stages": [["filing"]],
  "quotedAt": "2026-09-25T12:00:00Z",
  "quoteToken": "mq1.eyJjb3N0TXVsdGlwbGllciI6IjEi...",
  "validUntil": "2026-09-25T12:05:00Z"
}

Constraints

• Free: a quote does not pay providers or create a job.
• With a hosted OAuth wallet, MCP quote_plan adds payment: status is ready (with the fundingCurrency and spendableNow that would pay; a free quote has neither), blocked (with action fund_wallet or reconnect), or not_verified when the wallet could not be read in time. It is a snapshot; create_job checks capacity again.
• Prices are server-derived; do not add client-owned prices to the plan.
• Free endpoints are priced at zero from the catalog and are not called while quoting.
• dynamic: true means a dependent node was priced with example values for its upstream inputs.
• Submission charges the signed quote without probing providers again until validUntil, 15 minutes after quoting; execution revalidates terms within accepted total and per-node limits.
• Repeating a quote for the same endpoint and input may reuse the provider's unexpired price instead of probing again.

Errors and recovery

Create a job

1. Persist an idempotency key before submitting.
2. Submit the unchanged quoted plan within the authorized budget.
3. Save the returned job ID and poll it.

• Hosted OAuth clients that already know a plan may pass max_total to create_job instead of quote_token and approved_total. Mercator quotes and submits in one call, and returns quote_changed without charging when the live total exceeds max_total.
• REST clients that already know a plan may send maxTotal instead of quoteToken and approvedTotal to POST /v1/jobs. Each request, including the paid retry, quotes the plan and fails with quote_changed before payment when the live total exceeds maxTotal.

{
  "approved_total": "{{QUOTED_TOTAL}}",
  "quote_token": "{{QUOTE_TOKEN}}",
  "idempotency_key": "{{IDEMPOTENCY_KEY}}",
  "plan": {
    "nodes": [{
      "id": "filing",
      "serviceId": "{{SERVICE_ID}}",
      "method": "{{METHOD}}",
      "path": "{{PATH}}",
      "input": {"query": "latest official NVIDIA SEC filing"},
      "dependsOn": []
    }]
  }
}

{
  "job": {"jobId": "123e4567-e89b-42d3-a456-426614174000", "status": "pending"},
  "next_action": "Poll get_job with the returned job_id."
}

Constraints

• Paid and side-effecting: the signed quote total is charged before execution.
• Every payment path requires the quote token and the exact approved total.
• Hosted OAuth limits authorize spending; respect any additional user budget.
• Native MPP and local wallets need quote approval or a sufficient explicit budget before paying.
• Hosted MCP authorization does not create a local wallet.
• MCP challenge clients handle the payment challenge through MCP metadata.
• Keep retries bound to the same payer, key, and unchanged plan. A new key can create a second paid job.
• Configured Stripe SPT payments require exact whole-cent totals of at least $0.01. Retry with the same SPT and idempotency key; a new SPT is a new payment identity.

Errors and recovery

Get a job

• Send Prefer: wait=20 on POST /v1/jobs or GET /v1/jobs/{jobId} to receive the finished job in the same response (at most 25 seconds); Preference-Applied echoes the honored wait. MCP get_job waits up to 20 seconds on its own.
• Poll with bounded backoff while still active; stop execution polling at a terminal status.
• Use summary mode for large results, then retrieve only the nodes you need.
• Present successful outputs first when a job partially succeeds.

mercator call get_job \
  --input '{
  "job_id": "123e4567-e89b-42d3-a456-426614174000",
  "result_mode": "summary"
}'

{
  "jobId": "123e4567-e89b-42d3-a456-426614174000",
  "status": "succeeded",
  "cached": true,
  "result": {},
  "result_mode": "summary",
  "result_node_ids": ["filing"],
  "summary": {"succeeded": 1, "failed": 0, "skipped": 0},
  "failures": []
}

Constraints

• Cached reads are free and do not execute providers again.
• Hosted job reads require the original payer; other supported payment modes use the private job ID.
• Job records, results, and charged idempotency records expire after 30 days.
• Disconnecting does not cancel execution.
• Free calls retry upstream 408, 425, 429, 5xx, network, and timeout failures up to three times with jitter and a bounded provider Retry-After; other upstream 4xx responses fail after one attempt. After a durable purchase claim, a paid provider request is attempted at most once.
• Each entry in failures has a closed reason and retryable, which is true only when an identical new job may succeed later. When known, it adds the upstream providerStatus, providerErrorKind, retryAfterSeconds, the provider attempts, and an error_id to quote in bug reports.
• provider_rate_limited and provider_unavailable with retryable: true are transient provider capacity failures. Quote a new plan for only the failed nodes later, splitting large batches for one service. When retryable is false, the provider may already have been paid, so do not resubmit.
• Completed purchases remain billable when other nodes fail.

Errors and recovery

Get node results

• Select a successful node from result_node_ids after a summary read.
• Use result_pointer to retrieve just the required field.
• Job and node-result reads ignore unknown query parameters, such as utm_* tags on shared links; invalid values for known parameters return 400 invalid_request.

mercator call get_job_details \
  --input '{
  "job_id": "123e4567-e89b-42d3-a456-426614174000",
  "node_id": "filing",
  "result_pointer": "/results/0"
}'

{
  "jobId": "123e4567-e89b-42d3-a456-426614174000",
  "nodeId": "filing",
  "resultPointer": "/results/0",
  "result": {"title": "Example filing", "url": "https://www.sec.gov/"}
}

Constraints

• Free; the node is never rerun.
• The same authentication and retention rules apply as for Get a job.

Errors and recovery

List and recover jobs

History defaults to 10 jobs per request and accepts a maximum limit of 100.

1. List jobs using the wallet that paid for them.
2. Select a returned jobId.
3. Use Get a job to retrieve cached outputs for free.

mercator call list_jobs \
  --input '{
  "limit": 10,
  "status": "succeeded"
}'

{
  "jobs": [{
    "jobId": "123e4567-e89b-42d3-a456-426614174000",
    "status": "succeeded",
    "services": ["parallel"],
    "resultAvailable": true,
    "expiresAt": "2026-10-02T12:00:00Z"
  }],
  "nextCursor": "123e4567-e89b-42d3-a456-426614174000"
}