Get objective diagnostics

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const response = await client.objectives.retrieveDiagnostics('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});

console.log(response.diagnostics);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
response = client.objectives.retrieve_diagnostics(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(response.diagnostics)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Objectives.GetDiagnostics(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveGetDiagnosticsParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Diagnostics)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

response = cadenya.objectives.retrieve_diagnostics(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(response)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/diagnostics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "diagnostics": {
    "contextLengths": {
      "systemPrompt": 123,
      "skillsMemory": 123,
      "episodicMemory": 123,
      "availableTools": 123,
      "toolDefinitions": 123,
      "userMessages": 123,
      "assistantMessages": 123,
      "toolResults": 123
    },
    "inputTokens": 123,
    "cachedInputTokens": 123
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

GET

workspaces

{workspaceId}

objectives

{objectiveId}

diagnostics

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const response = await client.objectives.retrieveDiagnostics('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});

console.log(response.diagnostics);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
response = client.objectives.retrieve_diagnostics(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(response.diagnostics)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.Objectives.GetDiagnostics(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveGetDiagnosticsParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Diagnostics)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

response = cadenya.objectives.retrieve_diagnostics(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(response)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/diagnostics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "diagnostics": {
    "contextLengths": {
      "systemPrompt": 123,
      "skillsMemory": 123,
      "episodicMemory": 123,
      "availableTools": 123,
      "toolDefinitions": 123,
      "userMessages": 123,
      "assistantMessages": 123,
      "toolResults": 123
    },
    "inputTokens": 123,
    "cachedInputTokens": 123
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

An agent that costs too much is almost always spending its window on something you did not expect: a tool set with three hundred tool definitions, a memory appendix nobody trimmed, a tool that returns a megabyte of JSON. This endpoint tells you which.

const { diagnostics } = await client.objectives.retrieveDiagnostics(objectiveId, { workspaceId });

console.log(diagnostics.inputTokens);        // 1348
console.log(diagnostics.contextLengths);
// { systemPrompt: 159, toolDefinitions: 1246, userMessages: 31,
//   assistantMessages: 258, toolResults: 935,
//   skillsMemory: 0, episodicMemory: 0, availableTools: 0 }

response, err := client.Objectives.GetDiagnostics(ctx, objectiveID,
	cadenya.ObjectiveGetDiagnosticsParams{WorkspaceID: cadenya.String(workspaceID)})

fmt.Println(response.Diagnostics.InputTokens) // 1348
fmt.Printf("%+v\n", response.Diagnostics.ContextLengths)
// {SystemPrompt:159 ToolDefinitions:1246 UserMessages:31
//  AssistantMessages:258 ToolResults:935 ...}

response = cadenya.objectives.retrieve_diagnostics(objective_id, workspace_id: workspace_id)

puts response.diagnostics.input_tokens # 1348
puts response.diagnostics.context_lengths

curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/diagnostics" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}"

Two different units, side by side

This is the thing to internalize before you build anything on this endpoint.

contextLengths values are character counts. Every one of them.
inputTokens and cachedInputTokens are tokens.

They sit on the same object with no unit in either name. An objective whose rendered system prompt is 41 characters long reports systemPrompt: 41, right next to inputTokens: 660.

Do not sum contextLengths and compare it to inputTokens. One is characters, the other tokens. Use the components to see proportions, and use inputTokens for the absolute number.

Characters rather than tokens is a deliberate choice: it stores the raw measurement, so the token estimate can improve without rewriting history. Divide the total by inputTokens if you want your model’s rough characters-per-token ratio.

What each component is

Field	What lands there
`systemPrompt`	The rendered `systemPromptTemplate`.
`toolDefinitions`	Every tool’s name, description, and JSON Schema.
`availableTools`	The discoverable-tools appendix, under progressive discovery.
`skillsMemory`	The manifest of your skills layers.
`episodicMemory`	The primer and table of what the agent has stored.
`userMessages`	Your turns.
`assistantMessages`	The agent’s turns, including its reasoning.
`toolResults`	What tools returned.

The interesting one is almost always toolDefinitions. In the sample above, before the agent had said a single word, tool definitions were 1,246 characters against a 159-character prompt. Every objective pays that on every model call. That is what tool filters and progressive discovery exist to shrink. The second most interesting is toolResults, which is what tool result clearing reclaims during compaction.

It only sees the current window

Diagnostics describe the objective’s live context window, and they grow as it runs:

t+3s    inputTokens=0     sys=0    toolDefs=0     user=0   asst=0    toolResults=0
t+12s   inputTokens=832   sys=159  toolDefs=1246  user=31  asst=0    toolResults=0
t+25s   inputTokens=1348  sys=159  toolDefs=1246  user=31  asst=258  toolResults=935

Everything reads zero before the first model call, because nothing has been assembled yet.

A terminal objective returns all zeros. STATE_FINALIZED, STATE_FAILED, STATE_CANCELLED, and STATE_TIMED_OUT all report inputTokens: 0 and every component at 0, even a run with sixty events behind it. The response is a 200, so you cannot tell “no data retained” from “used no context.”Read diagnostics while the objective is STATE_PENDING, STATE_RUNNING, or STATE_WAITING. For a post-mortem, list its context windows instead: those retain promptTokens and completionTokens per window, though not the component breakdown.

Use it to find the fat

Grab a healthy objective mid-run and rank the components. The one at the top is where your money is.

const { diagnostics } = await client.objectives.retrieveDiagnostics(objectiveId, { workspaceId });
const total = Object.values(diagnostics.contextLengths).reduce((a, b) => a + b, 0);

for (const [component, chars] of Object.entries(diagnostics.contextLengths).sort((a, b) => b[1] - a[1])) {
  if (chars === 0) continue;
  console.log(component.padEnd(20), `${((100 * chars) / total).toFixed(1)}%`);
}
// toolDefinitions      47.4%
// toolResults          35.6%
// assistantMessages    9.8%
// systemPrompt         6.0%
// userMessages         1.2%

What to do with the answer:

toolDefinitions dominates. Narrow the tool set with an include filter, or turn on progressive discovery so definitions load on demand.
toolResults dominates. Enable toolResultClearing on the variation, or make the tool return less.
skillsMemory dominates. Your manifest is too big. Split the layer, or tighten the entry descriptions.
assistantMessages dominates. The agent is thinking in circles. That is a prompt problem, not a config one.

cachedInputTokens tells you how much of the window the provider served from its prompt cache. A high number is good: the stable head of your prompt (system prompt, tool definitions) is being reused across turns rather than re-billed.

List context windows

Per-window token counts, retained after the objective ends.

Preventing tool bloat

The fix when toolDefinitions is eating your window.

Create a variation

Compaction, tool result clearing, and the trigger threshold.

Compaction

What happens when the window fills anyway.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

objectiveId

string

required

The ID of the objective. Supports "external_id:" prefix for external IDs.

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Response

diagnostics

object

required

Diagnostics from the objective's most recent iteration.

Show child attributes

​Two different units, side by side

​What each component is

​It only sees the current window

​Use it to find the fat

​Related

List context windows

Preventing tool bloat

Create a variation

Compaction

Authorizations

Path Parameters

Response

Two different units, side by side

What each component is

It only sees the current window

Use it to find the fat

Related