> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage execution and billing

> Learn about asynchronous execution, idempotent retries, cost reservations, settlement, and artifact retrieval.

## Overview

This page follows paid tools from quoting through reservation, asynchronous execution, settlement, and artifact retrieval. Track long-running work by execution ID instead of keeping an HTTP connection open.

## Understand execution and billing

`POST /tools/quote` returns the price version, minimum charge, and maximum reservation for the current input. Quotes are free: they neither invoke external services nor reserve funds.

To execute, use the same `tool` and `arguments` as the quote and add these two fields:

* `priceVersion` — The price version returned by the quote
* `maximumChargeMicros` — The maximum reservation returned by the quote

If prices have changed or the supplied cap is too low, the request is rejected before work starts. Obtain a new quote and review it again.

## Reserve and settle charges

When paid work is accepted, the maximum reservation is temporarily held from the prepaid USD balance. After completion, the actual charge is settled and the unused reservation is returned to the balance.

| Field | Meaning |
| - | - |
| `reservedMicros` | Maximum amount reserved on acceptance; retains its original value after completion. |
| `chargedMicros` | Settled charge after completion or failure. A processing-time value of `0` means settlement is pending. |
| `currency` | `usd`. 1 USD equals 1,000,000 micros. |

Failures and cancellations can still settle actual costs already incurred by external processing. Charges never automatically exceed the maximum reservation.

## Track execution status

Acceptance returns HTTP 202 and an execution ID. Follow `Retry-After: 5` and poll the same ID at intervals of at least five seconds.

| Status | Meaning | Next action |
| - | - | - |
| `queued` | Waiting to start | Wait at least five seconds and check again |
| `running` | Processing | Poll the same execution ID |
| `waiting` | Waiting for external processing | Poll the same execution ID |
| `succeeded` | Succeeded and settled | Read `output` and `chargedMicros` |
| `failed` | Failed; incurred costs settled | Read `errorCode` and the settled charge |
| `cancelled` | Cancellation completed | Check the settled charge |
| `needs_review` | Result or cost requires review | Do not rerun; contact support with the execution ID |

## Prevent duplicates with idempotency keys

An idempotency key identifies a request so that accidentally sending it multiple times does not create separate executions. Paid `POST /tools/{tool}` requests require the `Idempotency-Key` header.

Keys must be 8–128 characters using letters, digits, `.`, `_`, `:`, or `-`. Generate one per logical request and store it with the execution ID.

* Resending the same API key, body, and idempotency key returns the same execution.
* Changing the body or API key while reusing the idempotency key returns HTTP 409.
* After a connection failure, resend without changing the body or idempotency key.
* Resending a `needs_review` request with a new idempotency key creates another paid execution.

> [!WARNING]
>
> A missing response does not prove that the execution was not accepted. Do not create a new idempotency key when the outcome is unknown.

## Cancel an execution

`POST /tools/executions/{id}/cancel` requests that work which has not started be stopped. The key that created the execution or a project `ADMIN` can request cancellation.

Once external processing has started, a cancellation request may not undo the work or its cost. Check `cancelRequested` and the final `status` and `chargedMicros`.

## Retrieve artifacts

Generated images, audio, and video appear in `output.artifacts` as file IDs, formats, sizes, hashes, and expiration dates. The execution result does not contain file contents or permanent URLs.

Call `GET /tools/executions/{id}/artifacts/{artifactId}/download` to obtain a download URL valid for up to five minutes. Stored files expire after 30 days.

Even temporary download URLs grant access to private data. Do not log or publish them, and do not append the Developer Platform API key to them.

## Related pages

See these pages for your first execution and endpoint details.

* [Get started](https://docs.noimosai.com/developers/api/getting-started.md)
* [API reference](https://docs.noimosai.com/developers/api/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.