Ask

Use Ask when you do not know which source answers the question, or when the answer needs several. Apiosk reads the question, matches sources and operations, prices a plan, and runs it on your approval. Ask and direct calls use the same source catalogue, the same prices and the same ledger. There are no Ask-only sources. Use a fixed workflow for a reproducible company or tender dossier with explicit country coverage. Supply either question or workflow.

Plan a question

POST /v2/ask

Requires ask:create.

curl https://gateway.apiosk.com/v2/ask \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Idempotency-Key: intent-signals-2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{"question":"Find the registered address and the latest filed accounts for Mollie B.V.","limit":5}'

Field	Type	Default	Meaning
`question`	string, 1–4000 chars	required unless `workflow` is supplied	The question, in the user’s own words
`execution_mode`	`"plan"` or `"auto"`	`"plan"`	`auto` runs the plan straight away when it fits `max_spend`
`max_spend`	decimal USD	none	Required with `auto`; the ceiling for the whole plan
`limit`	integer 1–50	none	Cap the number of result documents returned
`wait_seconds`	integer 0–55	25	With `auto`, how long to wait before answering `202`

{
  "id": "5c1f…",
  "status": "requires_approval",
  "question": "Find the registered address and the latest filed accounts for Mollie B.V.",
  "plan": {
    "quote_ref": "9ad2…",
    "expires_at": "2026-09-22T18:40:00Z",
    "steps": [
      { "source_id": "kvk-dutch-business-register", "operation": "company_registry.search", "name": "Company search",
        "conditional": false,
        "estimated_cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" } },
      { "source_id": "kvk-dutch-business-register", "operation": "company.financial-statements", "name": "Annual accounts",
        "conditional": false,
        "estimated_cost": { "amount": 0.115, "amount_micro_usd": "115000", "currency": "USD" } }
    ],
    "estimated_total": { "amount": 0.138, "amount_micro_usd": "138000", "currency": "USD" }
  },
  "usage": { "sources": [], "cost": { "amount": 0, "amount_micro_usd": "0", "currency": "USD" } },
  "errors": []
}

The plan and amounts above illustrate the response shape; read live source details for current prices. Planning is free. estimated_total is the maximum the run may cost; you are charged what the sources actually cost, which can be less.

Run it later

POST /v2/asks/{id}/run

Requires ask:execute.

curl https://gateway.apiosk.com/v2/asks/5c1f…/run \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_spend":1.00,"limit":5}'

Running an ask twice returns the same run. It never starts a second purchase.

Run it immediately

{
  "question": "Find the registered address and the latest filed accounts for Mollie B.V.",
  "execution_mode": "auto",
  "max_spend": 1.00,
  "limit": 5
}

With auto, Apiosk runs the plan without a second call, but only when all four hold: the plan’s maximum cost is within max_spend, within the key’s per-request limit, within what the key may still spend this month, and within the organisation’s balance. If the plan costs more than max_spend, you get the plan back, unrun and unbilled:

{
  "id": "5c1f…",
  "status": "requires_approval",
  "approval_required_reason": {
    "code": "max_spend",
    "message": "The plan's maximum cost is above max_spend, so it was not run. Nothing was charged."
  },
  "plan": { "estimated_total": { "amount": 1.44, "amount_micro_usd": "1440000", "currency": "USD" } }
}

Clarify before buying

A needs_input response may contain field schemas, a natural language message, or both. Ask the person for the missing context; never fill it in by guessing. A needs_selection response offers candidates, so ask which entity they meant. When the response includes continuation, use POST /v2/asks/{id}/continue to select a candidate or supply the requested structured value on the same saved task. A paid search is not repeated. Selection resumes the remaining work under the original valid approval; a new quote created by supplied input requires an explicit /run. A natural-language clarification without continuation still requires a new clarified Ask. Inspect the earlier run’s results and usage first; do not automatically repeat a paid request. Document uploads use the App.

Statuses

`status`	Meaning	What to do
`requires_approval`	A priced plan is ready	`POST /v2/asks/{id}/run`
`running`	The plan is executing (HTTP `202`)	Poll `GET /v2/runs/{id}`
`completed`	Every step finished	Read `answer`, `results`, `usage`
`partial`	Some steps failed or were skipped	Read `errors` beside the results you did get
`needs_input`	The question is missing something	Use `continuation` for structured input, or read the clarification in `message`
`needs_selection`	Several entities match	Choose from `candidates` and continue the saved task through `/continue`
`unsupported`	No source can answer this	Nothing was charged
`failed`	The run failed (HTTP `502`)	`error` and `errors` say why; see `usage` for what was charged

Status codes

Status	Code	Meaning
200	—	A plan, or a finished run
202	—	Still running after `wait_seconds`
400	`invalid_request`	`question` empty or over 4000 characters, or `auto` without `max_spend`
401	`invalid_api_key`	See Authentication
402	`insufficient_balance` / `spend_limit_exceeded`	Nothing was charged
403	`insufficient_scope`	`ask:create`, and `ask:execute` for running
409	`idempotency_conflict` / `plan_expired` / `plan_not_ready`	Ask again for a fresh plan
422	`unsupported`	No source can answer the question
429	`rate_limit_exceeded`	Wait a minute, then retry with the same key
502	`source_error`	The run failed; read `usage` for what was charged

Buy data

Use cases

Operating it

API Reference

Ask

Plan a question

Run it later

Run it immediately

Clarify before buying

Statuses

Status codes

​Plan a question

​Run it later

​Run it immediately

​Clarify before buying

​Statuses

​Status codes

Plan a question

Run it later

Run it immediately

Clarify before buying

Statuses

Status codes