Skip to content
Fous Docs
MarkdownStudio

Run a query

Send a query in plain language and get the result. Fous picks the methods, fills their inputs and runs them.

Send POST /v1/runs a query instead of a method. Fous finds the methods that fit, fills their inputs, runs up to three and returns one result.

Terminal
curl https://api.fous.com/v1/runs \  -H "Authorization: Bearer $FOUS_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "query": "Which public holidays does Germany have in 2027?",    "wait": 30  }'
JSON
{  "id": "run_01m5m1a2b3c4d5e6f7g8h9j0kq",  "status": "completed",  "data": {    "country_name": "Germany",    "year": 2027,    "holidays": [      {        "date": "2027-01-01",        "weekday": "Friday",        "english_name": "New Year's Day",        "local_name": "Neujahr",        "nationwide": "yes",        "regions": [],        "type": "Public"      }    ]  },  "truncated": false,  "steps": [    {      "method": {        "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",        "slug": "date.nager.at/list_public_holidays",        "version": 2      },      "input": { "country": "DE", "year": 2027 },      "status": "completed"    }  ],  "source": "methods",  "cost": { "credits": 5 },  "duration_ms": 4120}
FieldMeaning
queryWhat you want, 3 to 2,000 characters, with the values that matter.
output_schemaOptional. A JSON Schema object; data comes back in that shape.
platformOptional. The one site to answer from.
waitOptional. Seconds to wait, 0 to 60, 30 by default.

The result

  • steps: each method call, with the version and the input Fous chose.
  • source: methods, or live when the answer came from the live web, with its pages in sources.
  • uncovered: parts no method covers yet, answered from the live web.
  • status: "partial": part is missing. empty: true: the named site has nothing.

A slow query answers 202 and is read or cancelled by id, like a slow run.

When there is no result

A query with no result is free and fails with the steps it tried:

JSON
{  "error": {    "code": "not_found",    "message": "No method fits this request and no live source had the answer.",    "next_step": "Try other words, name the website with platform, or build a method with POST /v1/builds. Nothing was charged.",    "steps": [],    "source": "live",    "run_id": "run_01m5m1a2b3c4d5e6f7g8h9j0kq",    "doc_url": "https://docs.fous.com/guides/errors#not_found",    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"  }}

It can also fail with 403 connection_required when the methods that fit need an account. A query never builds: send the request to POST /v1/builds to make the missing method.

Query or run?

Run a method when you know which one: its output follows its schema and costs 1 credit, not 5. Send a query when you do not know the method, need calls chained, or want your own shape.