Runs

The Run object

idstringrequired
run_ followed by 26 characters; results are kept 24 hours.
statusstringrequired
partial (query): an answer, but not all of what was asked.
runningcompletedpartialfailed
methodobject
The method and the version that ran.
Show child attributesHide child attributes
- idstring
- slugstring or null
- versioninteger
- latest_versioninteger
  POST /v1/runs: the method’s newest version.
dataJSON value
The result, shaped by the method’s output_schema (query: by your output_schema when you send one).
noticestring
A completed run that came back empty or incomplete while the version is under repair: it cost nothing, and when the repair is back at the latest.
emptyboolean
The site answered and has nothing for this input (still a success).
rawJSON value
With include_raw: the site’s own response.
truncatedboolean
The answer is not complete: the site had more than the run could read, or the output was over 10 MB and its longest list was cut. missing says what.
missingarray of string
What the answer lacks, in plain words (a source that failed, items that could not be read, pages not read). Only when something is.
costobject
Show child attributesHide child attributes
- creditsinteger
duration_msinteger
sourcestring
query: methods answered, or a live web search did.
methodslive
stepsarray of object
query: the method calls made (method: id, slug and the version that ran) and their status.
sourcesarray of object
query, live answers: the pages the data came from.
uncoveredarray of string
query: the things asked for that no method provides yet, answered from the live web beside the method calls.
created_atstring
running only.

Run

{  "id": "run_01m5m0ere4fzdte37jhhn33ycd",  "status": "completed",  "method": {    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",    "slug": "date.nager.at/list_public_holidays",    "version": 2,    "latest_version": 2  },  "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"      },      {        "date": "2027-01-06",        "weekday": "Wednesday",        "english_name": "Epiphany",        "local_name": "Heilige Drei Könige",        "nationwide": "no",        "regions": [          "Baden-Württemberg",          "Bavaria",          "Saxony-Anhalt"        ],        "type": "Public"      }    ]  },  "truncated": false,  "cost": {    "credits": 1  },  "duration_ms": 1751}

Two ways to run. With method (manual): runs that method with inputs that fit its input_schema (1 credit). With query (auto): Fous finds read methods, fills their inputs, runs up to three and returns the data, shaped by output_schema when you send one; when no method fits, it answers from the live web (source "live", sources named). A query costs 5 credits, nothing when it has no answer (404 not_found with run_id); status is partial when not all of what was asked was found; one the request check turns away answers 422 request_refused. Both wait up to wait seconds (default 30). A run still going then answers 202 with status "running" and goes on: read it with GET /v1/runs/{id}, or stop it with POST /v1/runs/{id}/cancel (nothing is charged). A query ends within 3 minutes. Hanging up before any answer stops a query; after a 202 it goes on.

Request body

Required, JSON. One of:

Run a method

methodstringrequired
The method’s id (mth_…) or slug (<domain>/<name>); add @N to run version N instead of the one your organization uses (its first run sets it).
inputobjectOptional
Fits the method’s input_schema; an input sent as null counts as not sent.
connectionstringOptional
A conn_ id, when the method needs an account and you want one other than the default.
include_rawbooleanOptional
Also return the site’s own response as raw.
waitintegerOptional
Seconds to wait for the answer, 0 to 60 (default 30); a longer run answers 202 and goes on.

Send a query

querystringrequired
The data you want, in plain words.
output_schemaobjectOptional
A JSON Schema object (type object) for the answer’s shape.
platformstringOptional
Limit it to one site.
waitintegerOptional
Seconds to wait for the answer, 0 to 60 (default 30); a longer query answers 202 and goes on.

Returns

A Run object.

200Completed (data may be empty: true when the site has nothing).
202Still running. The same Run, with status "running".

Errors

Status	Code	When
400	`invalid_request`	Both or neither of method and query, a body that does not fit, or an output_schema that is not an object
402	`insufficient_credits`	Not enough credits
403	`connection_required`	The method needs a connected account
404	`not_found`	No such method or version, or a query that found no answer (with run_id and steps)
422	`invalid_inputrequest_refused`	The input does not fit (invalid_input), or the request check turned a query away (request_refused)
429	`rate_limited`	Too many requests
503	`method_repairingupstream_errorupstream_blockedupstream_timeoutservice_unavailable`	The site failed, refused the request or did not answer in time (upstream_error, upstream_blocked, upstream_timeout), the version is under repair (method_repairing, with Retry-After), or billing is briefly unavailable (service_unavailable)

Run a method

curl 'https://api.fous.com/v1/runs' \  -H "Authorization: Bearer $FOUS_API_KEY" \  -H 'Content-Type: application/json' \  -d '{    "method": "date.nager.at/list_public_holidays",    "input": {      "country": "DE",      "year": 2027    }  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/runs', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    method: 'date.nager.at/list_public_holidays',    input: {      country: 'DE',      year: 2027    }  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result.data);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/runs",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "method": "date.nager.at/list_public_holidays",        "input": {            "country": "DE",            "year": 2027        }    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result["data"])

Sent with your key, kept for this tab only. A run uses credits like any call.

Send a query

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?"  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/runs', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    query: 'Which public holidays does Germany have in 2027?'  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result.data);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/runs",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "query": "Which public holidays does Germany have in 2027?"    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result["data"])

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "id": "run_01m5m0ere4fzdte37jhhn33ycd",  "status": "completed",  "method": {    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",    "slug": "date.nager.at/list_public_holidays",    "version": 2,    "latest_version": 2  },  "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"      },      {        "date": "2027-01-06",        "weekday": "Wednesday",        "english_name": "Epiphany",        "local_name": "Heilige Drei Könige",        "nationwide": "no",        "regions": [          "Baden-Württemberg",          "Bavaria",          "Saxony-Anhalt"        ],        "type": "Public"      }    ]  },  "truncated": false,  "cost": {    "credits": 1  },  "duration_ms": 1751}

{  "id": "run_01m5m0ere4fzdte37jhhn33ycd",  "status": "running",  "method": {    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",    "slug": "date.nager.at/list_public_holidays",    "version": 2,    "latest_version": 2  },  "created_at": "2026-10-23T09:11:15.035Z"}

{  "error": {    "code": "invalid_request",    "message": "Send either method (with its input) or query, not both.",    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"  }}

Get a run

Status and result of a run (a method’s or a query’s), kept 24 hours. Free. A failed run answers with its own status and error, which carries run_id (and for a query its steps).

Path parameters

idstringrequired

Query parameters

waitintegerdefault 0Optional
Seconds to hold the answer while it is still running, 0 to 60.

Returns

A Run object.

200Finished.
202Still running. The same Run, with status "running".

Errors

Status	Code	When
403	`connection_required`	The run needed a connected account
404	`not_found`	Unknown or expired, or a query that found no answer (with its run_id)
409	`conflict`	The run was stopped (reason stopped)
422	`invalid_input`	The site refused the input
503	`upstream_errorupstream_blockedupstream_timeoutmethod_unavailable`	The site failed, refused the request or did not answer in time (upstream_error, upstream_blocked, upstream_timeout), or the method is broken (method_unavailable)

curl 'https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd' \  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd', {  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.get(    "https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "id": "run_01m5m0ere4fzdte37jhhn33ycd",  "status": "completed",  "method": {    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",    "slug": "date.nager.at/list_public_holidays",    "version": 2,    "latest_version": 2  },  "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"      },      {        "date": "2027-01-06",        "weekday": "Wednesday",        "english_name": "Epiphany",        "local_name": "Heilige Drei Könige",        "nationwide": "no",        "regions": [          "Baden-Württemberg",          "Bavaria",          "Saxony-Anhalt"        ],        "type": "Public"      }    ]  },  "truncated": false,  "cost": {    "credits": 1  },  "duration_ms": 1751}

{  "id": "run_01m5m0ere4fzdte37jhhn33ycd",  "status": "running",  "created_at": "2026-10-23T09:11:15.035Z"}

{  "error": {    "code": "connection_required",    "message": "Your notion.so account is no longer signed in. The site sent the request to its sign-in page.",    "next_step": "Sign in at connect_url (a Fous Studio page), or with POST /v1/connections/conn_01m5k2v8c4n6p8r0t2w4y6a8c0/sign-in, then run again. Nothing was charged.",    "connect": {      "platform": "notion.so",      "type": "session",      "connection_id": "conn_01m5k2v8c4n6p8r0t2w4y6a8c0"    },    "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5k2v8c4n6p8r0t2w4y6a8c0",    "run_id": "run_01m5m0ere4fzdte37jhhn33ycd",    "doc_url": "https://docs.fous.com/guides/errors#connection_required",    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"  }}

Cancel a run

Cancels a run (a method’s or a query’s) that is still going: nothing is charged, reading it afterwards answers 409 conflict with reason "stopped", and what the site answers after that is dropped. Free.

Path parameters

idstringrequired

Returns

200Stopped.

The answer has these fields:

idstring
stoppedboolean

Errors

Status	Code	When
404	`not_found`	Unknown or expired
409	`conflict`	Already ended

curl 'https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd/cancel' \  -X POST \  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd/cancel', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd/cancel",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "id": "run_01m5m0ere4fzdte37jhhn33ycd",  "stopped": true}

{  "error": {    "code": "not_found",    "message": "No such run.",    "doc_url": "https://docs.fous.com/guides/errors#not_found",    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"  }}

The Run object

Run a method or a query

Request body

Run a method

Send a query

Returns

Errors

Get a run

Path parameters

Query parameters

Returns

Errors

Cancel a run

Path parameters

Returns

Errors