History, errors and usage
Understand what ran, what it received and what was counted.
Open the operation that matters
History keeps saved-agent operation input, result, instructions and the included context for 30 days. Saved-task runs also retain the task name, revision and operation settings; editing a task does not rewrite an earlier operation. Reference texts and Knowledge evidence are tied to the revisions used by that operation. Editing today’s document does not rewrite yesterday’s record.
A decision and its action execution are distinct. Inspect the chosen action, parameters and recorded execution result before concluding that an external side effect happened.
Keep a result even if recording failed
if not result.success:
print(result.error_code, result.error)
if result.history_error:
# Preserve the operation result in your own logs or storage.
print("History error:", result.history_error)
print(result.usage)
print(result.knowledge_usage)This snippet handles a result returned by one of the operations. Setup and API failures can raise APIError, TransportError or ProtocolError. Model-operation refusals are normally returned as results. TransportError preserves request_id when no response was received; inspect History before retrying an uncertain outcome. Unknown usage remains None.
Unknown usage is not zero
| Field | Meaning |
|---|---|
| usage.input_tokens / usage.output_tokens | Provider-reported generation tokens, including known failed replies |
| usage.uncounted_requests | Requests for which generation usage was not reported |
| knowledge_usage | Search embedding usage, separate from generation |
| usage is None | No provider-reported generation usage; not proof of zero consumption |
Usage in the dashboard shows hosted consumption and recorded charges. Knowledge preparation and search are tracked separately from generation. A failure after a provider request can still have usage.
Common errors and what to change
| Code | Next step |
|---|---|
| invalid_reply | Inspect the input/schema, reduce the task or choose a more capable model |
| documents_too_large | Reduce reference texts. JavaScript can set documentBudget; Python and HTTP use the default 6000 |
| model_context_too_large | Reduce the complete request or use a model with a suitable window |
| context_key_not_found | Check the selected context keys in this data scope |
| knowledge_not_ready / knowledge_prepare_failed | Inspect the source’s preparation state in the dashboard |
| knowledge_query_too_large | Supply a shorter explicit Knowledge query |
| knowledge_empty / knowledge_no_evidence | Check connected sources; this does not prove an answer is absent |
| agent_paused | Check the saved agent’s pause state |
| spend_cap_reached | Check the team’s model credit |
| key_refused / platform_unavailable | Check setup and connectivity before retrying |
For HTTP transport errors and retry IDs, see the HTTP API. The SDK reference includes additional options and error codes.