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

JavaScript
if (!result.success) {
  console.error(result.errorCode, result.error);
}
if (result.historyError) {
  // Preserve the operation result in your own logs or storage.
  console.error('History error:', result.historyError);
}
console.log(result.usage);
console.log(result.knowledgeUsage);

This snippet handles a result returned by one of the operations. Loading or creating an agent can throw an AgentError; operation failures are normally returned as results.

Unknown usage is not zero

FieldMeaning
usage.inputTokens / outputTokensGeneration tokens the provider reported, including known failed replies
usage.uncountedRequestsRequests for which generation usage was not reported
knowledgeUsageSearch embedding usage, separate from generation
No usage objectNo 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.