> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Send tool outputs

POST https://your-org.cloudraker.run/v2/machines/runs/{id}/tool-outputs
Content-Type: application/json

Sends the outputs of the pending tool calls of a run. An output that does not match the tool schema gives `400`, and the call stays pending. Only the credential that started the run can send it. The answer comes at the next stop of the run, or at the end of the wait: `Prefer: wait=N` (1 to 90), default 30 seconds. A run that ended gives `409 not_waiting`. Needs the scope `machines`.

Reference: https://docs.cloudraker.com/paperwork/v2/api/machines/submit-tool-outputs

## Authentication

- `Authorization` header (bearer token, required) — An API key (`crk_`), an exchanged token (`crt_`) or a JWT of a trusted issuer. The credential needs the scope of the capability. Read the description of each route.

## Request

### Path parameters

- `id` (string, required) — The run id. It is also the job id: `job_` and a ULID.

### Query parameters

- `wait` (integer, optional) — The alias of `Prefer: wait=N`. The `Prefer` header wins when both are there.

### Headers

- `Prefer` (string, optional) — `wait=N` (1 to 90) holds the request up to N seconds. `respond-async` answers `202` at once. Behind a proxy with a 60 second idle timeout, use `wait=55` or less.

### Body (application/json)

This endpoint expects a ToolOutputsRequest.

- `tool_outputs` (list of ToolOutputsRequestToolOutputsItems, required)

## Response

### 200

The run at its next stop.

- `object` ("machine_run", required)
- `id` (string, required) — The run id. It is also the job id.
- `machine` (string, required, nullable) — Null for an inline run.
- `version` (integer, required, nullable)
- `ir_hash` (string, required)
- `job_status` (enum, required, nullable)
  - Allowed values: `queued`, `running`, `needs_input`, `succeeded`, `failed`, `cancelled`, `expired`
- `status` (enum, required)
  - Allowed values: `new`, `running`, `waiting`, `held`, `done`, `refused`, `aborted`, `error`, `cancelled`, `expired`
- `outcome` (enum, required, nullable)
  - Allowed values: `done`, `refused`, `aborted`, `held`
- `required_action` (RequiredAction, required, nullable) — What the run waits for: tool outputs, the answer of a person, or an input. Send it with the route of its type.
- `report` (string, required, nullable)
- `hold` (MachineRunHold, required, nullable)
- `diverged` (string, required, nullable)
- `error` (MachineRunError, required, nullable)
- `entries` (integer, required) — The log entries so far.
- `usage` (MachineRunUsage, required)
- `created_at` (datetime, required)
- `ended_at` (datetime, required, nullable)

## Errors

### 400 Bad Request Error

An error. The `code` is one of: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 401 Unauthorized Error

An error. The `code` is one of: `missing_credential`, `invalid_api_key`, `invalid_token`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 402 Payment Required Error

An error. The `code` is one of: `credits_exhausted`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 403 Forbidden Error

An error. The `code` is one of: `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 404 Not Found Error

An error. The `code` is one of: `not_found`, `tenant_not_found`, `job_not_found`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 409 Conflict Error

An error. The `code` is one of: `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 429 Too Many Requests Error

An error. The `code` is one of: `rate_limit_exceeded`, `concurrency_limited`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 500 Internal Server Error

An error. The `code` is one of: `internal_error`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

### 503 Service Unavailable Error

An error. The `code` is one of: `capability_unavailable`.

- `code` (enum, required) — The error code.
  - Allowed values: `invalid_request`, `wait_out_of_range`, `deadline_not_supported`, `procedure_invalid`, `missing_credential`, `invalid_api_key`, `invalid_token`, `credits_exhausted`, `insufficient_scope`, `production_access_disabled`, `test_key_not_allowed`, `not_found`, `tenant_not_found`, `job_not_found`, `idempotency_key_reused`, `job_not_cancellable`, `version_conflict`, `not_waiting`, `rate_limit_exceeded`, `concurrency_limited`, `internal_error`, `capability_unavailable`
- `message` (string, required) — A text for the developer. Do not parse it.
- `retryable` (boolean, required) — True when the same request can succeed later.
- `requestId` (string, required) — The value of the `x-request-id` answer header.
- `docUrl` (string, optional) — The docs page of this code.
- `details` (any, optional) — The validation issues of `invalid_request`.

## Types

### ToolOutputsRequestToolOutputsItems

- `tool_call_id` (string, required)
- `output` (any, required) — The output. With `is_error`, an object `{code, message, retryable?}`: a `code` of the tool `x-errors` matches an `on_error` case.
- `is_error` (boolean, optional) — True for an error output.

### RequiredAction

What the run waits for: tool outputs, the answer of a person, or an input. Send it with the route of its type.

- RequiredAction0
- RequiredAction1
- RequiredAction2

### MachineRunHold

- `code` (string, required)
- `reason` (string, required)
- `attach` (list of any, required)

### MachineRunError

- `code` (string, required)
- `message` (string, required)
- `cause` (enum, optional)
  - Allowed values: `engine_error`, `replay_diverged`, `log_limit`

### MachineRunUsage

- `model_calls` (integer, required)
- `decide_calls` (integer, required)
- `prompt_tokens` (integer, required)
- `completion_tokens` (integer, required)

### RequiredAction0

- `type` ("tool_calls", required)
- `tool_calls` (list of RequiredActionOneOf0ToolCallsItems, required)

### RequiredAction1

- `type` ("answer", required)
- `answer` (RequiredActionOneOf1Answer, required)

### RequiredAction2

- `type` ("inputs", required)
- `await_seq` (integer, required, nullable)
- `inputs` (list of RequiredActionOneOf2InputsItems, required)

### RequiredActionOneOf0ToolCallsItems

- `id` (string, required) — The tool call id.
- `name` (string, required)
- `idempotency_key` (string, required) — The same for each attempt of one step. Use the tool call id to run each attempt.
- `effect` (enum, required) — The effect of a step: `read`, `write` or `irreversible`.
  - Allowed values: `read`, `write`, `irreversible`
- `deadline_at` (datetime, required, nullable)
- `arguments` (map from string to any, optional)
- `arguments_truncated` (true, optional)

### RequiredActionOneOf1Answer

- `seq` (integer, required)
- `code` (string, required)
- `reason` (string, required)
- `question` (string, required, nullable)
- `schema` (map from string to any, required, nullable)
- `attachments` (list of any, optional)
- `attachments_truncated` (true, optional)

### RequiredActionOneOf2InputsItems

- `name` (string, required)
- `schema` (map from string to any, optional)
- `schema_truncated` (true, optional)

## Examples

**Request**

```json
{
  "tool_outputs": [
    {
      "tool_call_id": "mc_01JC3..._17",
      "output": null
    }
  ]
}
```

**Response**

```json
{
  "object": "string",
  "id": "string",
  "machine": "string",
  "version": 1,
  "ir_hash": "string",
  "job_status": "queued",
  "status": "new",
  "outcome": "done",
  "required_action": {
    "tool_calls": [
      {
        "arguments": {},
        "arguments_truncated": true,
        "deadline_at": "2026-11-07T14:02:11Z",
        "effect": "read",
        "id": "mc_01JC3..._17",
        "idempotency_key": "string",
        "name": "string"
      }
    ],
    "type": "string"
  },
  "report": "string",
  "hold": {
    "code": "string",
    "reason": "string",
    "attach": [
      null
    ]
  },
  "diverged": "string",
  "error": {
    "code": "string",
    "message": "string",
    "cause": "engine_error"
  },
  "entries": 1,
  "usage": {
    "model_calls": 1,
    "decide_calls": 1,
    "prompt_tokens": 1,
    "completion_tokens": 1
  },
  "created_at": "2026-11-07T14:02:11Z",
  "ended_at": "2026-11-07T14:02:11Z"
}
```

**SDK Code**

```python
import requests

url = "https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs"

payload = { "tool_outputs": [
        {
            "tool_call_id": "mc_01JC3..._17",
            "output": None
        }
    ] }
headers = {
    "Prefer": "wait=30",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs';
const options = {
  method: 'POST',
  headers: {
    Prefer: 'wait=30',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"tool_outputs":[{"tool_call_id":"mc_01JC3..._17","output":null}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs"

	payload := strings.NewReader("{\n  \"tool_outputs\": [\n    {\n      \"tool_call_id\": \"mc_01JC3..._17\",\n      \"output\": null\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Prefer", "wait=30")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Prefer"] = 'wait=30'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tool_outputs\": [\n    {\n      \"tool_call_id\": \"mc_01JC3..._17\",\n      \"output\": null\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs")
  .header("Prefer", "wait=30")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_outputs\": [\n    {\n      \"tool_call_id\": \"mc_01JC3..._17\",\n      \"output\": null\n    }\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs', [
  'body' => '{
  "tool_outputs": [
    {
      "tool_call_id": "mc_01JC3..._17",
      "output": null
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Prefer' => 'wait=30',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs");
var request = new RestRequest(Method.POST);
request.AddHeader("Prefer", "wait=30");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tool_outputs\": [\n    {\n      \"tool_call_id\": \"mc_01JC3..._17\",\n      \"output\": null\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Prefer": "wait=30",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["tool_outputs": [
    [
      "tool_call_id": "mc_01JC3..._17",
      "output": 
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://your-org.cloudraker.run/v2/machines/runs/id/tool-outputs")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```