Skip to content

Reference

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

Python
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

FieldMeaning
usage.input_tokens / usage.output_tokensProvider-reported generation tokens, including known failed replies
usage.uncounted_requestsRequests for which generation usage was not reported
knowledge_usageSearch embedding usage, separate from generation
usage is NoneNo 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

CodeNext step
invalid_replyInspect the input/schema, reduce the task or choose a more capable model
documents_too_largeReduce reference texts. JavaScript can set documentBudget; Python and HTTP use the default 6000
model_context_too_largeReduce the complete request or use a model with a suitable window
context_key_not_foundCheck the selected context keys in this data scope
knowledge_not_ready / knowledge_prepare_failedInspect the source’s preparation state in the dashboard
knowledge_query_too_largeSupply a shorter explicit Knowledge query
knowledge_empty / knowledge_no_evidenceCheck connected sources; this does not prove an answer is absent
agent_pausedCheck the saved agent’s pause state
spend_cap_reachedCheck the team’s model credit
key_refused / platform_unavailableCheck 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.