From API key to JSON result.

Quickstart

1. Create an account and confirm your email. Confirmation unlocks your 1,000 trial credits.
2. Create an API key. Open API keys in the console and copy your key.
3. Choose a published parser. Use its reference for supported fields and example input.
4. Submit a queued run and poll its result. Save the returned run ID before checking its status.

Authentication

Base URL: https://extracto.cloud/api/v1. Every parser and status request requires your account's API key. Send JSON requests with these headers:

X-API-KEY: ext_your_api_key
Content-Type: application/json
Accept: application/json

Keep keys on your server, outside public repositories and browser code. Revoke exposed keys in the console. A run is visible only to the account that created it.

Queued runs

Use POST /parsers/{tool}/queue for longer runs. The body contains an input object specific to the selected parser. An optional timeout accepts 30–600 seconds; it does not guarantee that the entire system will wait that long.

curl --request POST 'https://extracto.cloud/api/v1/parsers/instagram-posts/queue' \
  --header 'X-API-KEY: ext_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @- <<'JSON'
{
  "input": {
    "resultsType": "posts",
    "directUrls": [
      "https://www.instagram.com/nike/"
    ],
    "resultsLimit": 100,
    "searchType": "hashtag",
    "searchLimit": 10,
    "addParentData": false
  }
}
JSON

A stored queued run returns HTTP 202 Accepted. Read run.id and poll the API endpoint shown below. The response also includes credit reservation details.

{
  "success": true,
  "queued": true,
  "run": {
    "id": "7e1e15c2-2db4-4c17-a713-5432f47fb40f",
    "tool": "instagram-posts",
    "status": "queued"
  },
  "meta": {
    "credits_reserved": 10,
    "credits_remaining": 990
  }
}

curl 'https://extracto.cloud/api/v1/parser-runs/7e1e15c2-2db4-4c17-a713-5432f47fb40f' \
  --header 'X-API-KEY: ext_your_api_key' \
  --header 'Accept: application/json'

Poll about once every 5 seconds while run.status is queued or running. Stop when it becomes ok, partial, cancelled or error. Status checks and launches use separate per-user rate limits. You can also receive the result by webhook.

{
  "success": true,
  "run": {
    "id": "7e1e15c2-2db4-4c17-a713-5432f47fb40f",
    "tool": "instagram-posts",
    "status": "ok",
    "credits": 10,
    "count": 1,
    "result": [
      {
        "example": "Parser-specific fields appear here"
      }
    ],
    "error": null
  }
}

Successful queued output is in run.result. A failed run returns HTTP 200 for the status request with run.status: "error" and details in run.error. Check this state as well as the HTTP status. If submission cannot be stored, the API returns HTTP 503 without reserving credits.

Result webhooks

Add webhook_url to a queued or synchronous parser request to receive the saved result by HTTP POST. An optional webhook_secret (16–256 characters) signs delivery. Use a public HTTPS endpoint; internal addresses, credentials in URLs and redirects are rejected.

curl --request POST 'https://extracto.cloud/api/v1/parsers/instagram-posts/queue' \
  --header 'X-API-KEY: ext_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @- <<'JSON'
{
  "input": {
    "resultsType": "posts",
    "directUrls": [
      "https://www.instagram.com/nike/"
    ],
    "resultsLimit": 100,
    "searchType": "hashtag",
    "searchLimit": 10,
    "addParentData": false
  },
  "webhook_url": "https://your-service.com/extracto/results",
  "webhook_secret": "replace_with_your_random_secret"
}
JSON

If budget confirmation is required, first request an estimate and include your max_budget_usd and quote_token as described in budget confirmation. A rejected submission does not create a webhook delivery.

{
  "event": "parser_run.completed",
  "delivery_id": "extracto-run-7e1e15c2-2db4-4c17-a713-5432f47fb40f",
  "created_at": "2026-10-05T12:00:00Z",
  "run": {
    "id": "7e1e15c2-2db4-4c17-a713-5432f47fb40f",
    "tool": "instagram-posts",
    "status": "ok",
    "count": 1,
    "credits": 10,
    "duration_ms": 2500,
    "finished_at": "2026-10-05T12:00:00Z",
    "result": [
      {
        "example": "Complete parser-specific data, preserving its structure"
      }
    ],
    "error": null
  }
}

Events: parser_run.completed, parser_run.partial, parser_run.failed and parser_run.cancelled. Partial and cancelled runs include any saved rows. Failed runs include the error and have no result. Delivery starts after the result and final credit charge are saved.

Return a 2xx response within 15 seconds. Failed delivery has up to five attempts, with delays of 1 minute, 5 minutes, 15 minutes and 1 hour. Delivery is at least once: deduplicate using X-Extracto-Delivery-Id, which stays the same on every attempt. Delivery retries do not rerun the parser or charge credits.

Verify signatures

When a secret is provided, headers include X-Extracto-Timestamp and X-Extracto-Signature. Verify HMAC-SHA256 of timestamp + "." + rawRequestBody with your secret. Compare against the hex value after sha256= using a constant-time comparison. Check that the timestamp is recent (for example, within 5 minutes); each attempt gets a new timestamp. Verify before parsing the JSON.

Delivery status and retries

GET /api/v1/parser-runs/{uuid} includes run.webhook: state, attempts, delivery ID, last HTTP status, last error and delivery time. States are waiting, pending, processing, retrying, delivered or failed. The URL and secret are not returned.

curl --request POST 'https://extracto.cloud/api/v1/parser-runs/7e1e15c2-2db4-4c17-a713-5432f47fb40f/webhook/retry' \
  --header 'X-API-KEY: ext_your_api_key' \
  --header 'Accept: application/json'

The retry endpoint only resets failed delivery. Calling it for an active or delivered webhook does not create another delivery. Reusing an Idempotency-Key with a different webhook URL or secret returns HTTP 409; use a new key for a new task.

Synchronous requests

Use POST /parsers/{tool} to wait for a result in one request. Long runs can exceed your HTTP client or gateway timeout; use the queue when that is likely.

curl --request POST 'https://extracto.cloud/api/v1/parsers/instagram-posts' \
  --header 'X-API-KEY: ext_your_api_key' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @- <<'JSON'
{
  "input": {
    "resultsType": "posts",
    "directUrls": [
      "https://www.instagram.com/nike/"
    ],
    "resultsLimit": 100,
    "searchType": "hashtag",
    "searchLimit": 10,
    "addParentData": false
  }
}
JSON

{
  "success": true,
  "tool": "instagram-posts",
  "count": 1,
  "data": [
    {
      "example": "Parser-specific fields appear here"
    }
  ],
  "meta": {
    "credits": 10,
    "credits_remaining": 990
  }
}

Synchronous output is in data. Returned field names depend on the parser.

Safe launch retries

Send an Idempotency-Key header with 8–128 letters, digits, dots, underscores, colons or hyphens. Choose a fresh random key for each intentional task and keep that key for retries after a timeout or interrupted connection.

The same key and settings return the existing run without another queue job or credit reservation. Active runs return HTTP 202; terminal runs return HTTP 200. A replay includes Idempotent-Replayed: true and meta.idempotent_replay: true. Keys are scoped to your account across API keys and launch endpoints. Different input, timeout, email preference, parser or maximum budget with the same key returns HTTP 409. Object property order does not matter; array order does. A refreshed quote token does not change task identity.

Replays return a run wrapper with run and status_url, including for synchronous retries. A failed or cancelled run is also replayed; use a new key for an intentional new attempt. Requests without the header continue to start a new task each time. No-Code and Playground keep a pending launch key in session storage until the server confirms receipt.

Estimate and confirm a large run

POST the same input to /api/v1/parsers/{tool}/estimate to calculate credits and dollars without a provider run. When budget_enabled and confirmation_required are true, include the returned quote_token and a max_budget_usd value such as "6.00" in your launch body alongside input.

Confirmation is required above $4 of estimated customer cost. Quotes expire after ten minutes and are tied to your user, input and pricing. The maximum must cover the estimate; reduce the requested limit if it exceeds your budget. The full maximum is held from available credits, and final customer charges cannot exceed it, including cancelled runs. Provider account spending has separate limits. Small requests can optionally set a maximum too.

Try a small paid sample

Supported No-Code scrapers offer Review sample cost before a full launch. The sample requests up to five records from the first source, using the same selected options with smaller native limits. Some parsers return a single detail record or nested fields. It is a separate paid task, capped at the confirmed maximum and never above $1. You can inspect and export the saved data before choosing Run scraper for your unchanged full settings. Samples are illustrative; they do not guarantee coverage or total results for the full request.

API clients can POST their original input to /api/v1/parsers/{tool}/sample-estimate. This only returns bounded input, estimated credits and max_budget_usd; it launches no provider work. After reviewing, POST the original input, sample: true and the returned max_budget_usd to the regular queue endpoint, with a fresh Idempotency-Key. The server derives the bounded input again and enforces a 120-second timeout. A changed estimate can require another review. Saved status includes is_sample: true.

Samples share your balance, per-user rates, execution capacity and daily/monthly spending limits. A sample rejected before admission has no task or charge. Unsupported source modes or an estimate above $1 return HTTP 422 with a reason; the full request is never substituted. The full launch uses a separate key and incurs its own charge; sample charges are not deducted from a future full run.

Daily and monthly spending limits

Set your dollar limits in Settings. They apply to all API keys, No-Code tasks and scheduled subscriptions on your account. A zero limit disables that period. Days and calendar months reset at midnight UTC; settled charges are counted by completion time. Credit purchases and free previews do not consume these budgets.

New admissions account for completed usage and all active task reservations, including tasks carried over from an earlier period. If the available budget cannot cover the estimate or approved task maximum, the request returns HTTP 429 with code: "spending_limit" before launching or charging. Reduce the task size, adjust your limit, or wait for the next period. Do not rapidly retry this response. API rate and execution-capacity limits are separate.

Tasks accepted with a spending limit have a saved charge ceiling equal to their admitted reservation. Lowering a limit preserves that ceiling for already accepted tasks, so those tasks can finish above the newly lowered limit. Cancel outstanding tasks if you need to release their reservations. Budget-blocked scheduled checks are skipped, with later checks remaining on the usual schedule.

When settled spending reaches 80% or 100%, a warning appears in Notifications, once per threshold and UTC period. Verified accounts may also receive HTML email through the existing retryable delivery queue. Reservations reduce available budget but do not trigger actual-spending warnings.

Credits and costs

Your credit balance is shared by the Playground, API and scheduled subscriptions. A credit is a billing unit: 1,000 credits correspond to $1. One request may use multiple credits. There is currently no automatic credit expiry.

Before a run, Extracto estimates the cost from the parser configuration and input, then holds that amount from available credits. If you approve a maximum charge, the full maximum is held. Your balance is charged after results are saved, according to the configured pricing model and returned items, including enabled components where applicable. meta.credits_reserved is the queue estimate; run.credits is the recorded final usage. Synchronous results report usage in meta.credits.

Some parsers use a fixed run cost; others charge by results or components. Check the parser's reference and the Playground's estimate before running. A parser's requested item limit can affect the estimate.

Before execution, HTTP 402 means your balance cannot cover the estimated reservation. For a run with an approved maximum, final charges are capped at that maximum and results are preserved. For a run without a maximum, if the final cost exceeds the estimate and your remaining balance cannot cover the difference, the hold is released and results are withheld. Synchronous requests return HTTP 402; queued runs report an error in their saved status. Parser errors and worker timeout failures refund the reservation. A recovery task checks for abandoned runs every minute: running jobs become eligible after their requested timeout plus 300 seconds, and unstarted queued jobs after one hour. If your balance still looks incorrect, contact support with the run ID.

Errors and limits

The current allowance is separate per-user limits for launches, status checks and cost estimates, shared across keys, parser requests and status checks. It is the same for every credit package.

{
  "success": false,
  "tool": "instagram-posts",
  "error": "Not enough credits.",
  "meta": {
    "credits_required": 10,
    "credits_remaining": 5
  }
}

{
  "message": "The input field is required.",
  "errors": {
    "input": [
      "The input field is required."
    ]
  }
}

Parser failures can use error; authentication and validation responses can use message and errors. Handle both shapes. For an unexpected server error, preserve the run ID and check existing status before retrying a submission.

Parser reference

Each published parser has its own input schema, example request and output reference.

Need help?

Send your parser slug, run ID and a redacted request example to [email protected]. Keep API keys out of support messages.