List objective context windows

JavaScript

import Cadenya from '@cadenya/cadenya';

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

// Automatically fetches more pages as needed.
for await (const objectiveContextWindow of client.objectives.listContextWindows(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
)) {
  console.log(objectiveContextWindow.data);
}

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
page = client.objectives.list_context_windows(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
page = page.items[0]
print(page.data)

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"),
	)
	page, err := client.Objectives.ListContextWindows(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveListContextWindowsParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", page)
}

require "cadenya"

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

page = cadenya.objectives.list_context_windows(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(page)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/context_windows",
  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;
}

{
  "items": [
    {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "createdAt": "2023-11-07T05:31:56Z",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "labels": {},
        "externalId": "<string>"
      },
      "data": {
        "objectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
        "sequence": 123,
        "promptTokens": 123,
        "completionTokens": 123,
        "previousWindowContinueInstructions": "<string>"
      },
      "info": {
        "objective": {
          "id": "<string>",
          "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
          "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
          "createdAt": "2023-11-07T05:31:56Z",
          "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
          "labels": {},
          "externalId": "<string>"
        },
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

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

GET

workspaces

{workspaceId}

objectives

{objectiveId}

context_windows

JavaScript

import Cadenya from '@cadenya/cadenya';

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

// Automatically fetches more pages as needed.
for await (const objectiveContextWindow of client.objectives.listContextWindows(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
)) {
  console.log(objectiveContextWindow.data);
}

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
page = client.objectives.list_context_windows(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
page = page.items[0]
print(page.data)

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"),
	)
	page, err := client.Objectives.ListContextWindows(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveListContextWindowsParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", page)
}

require "cadenya"

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

page = cadenya.objectives.list_context_windows(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(page)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/context_windows",
  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;
}

{
  "items": [
    {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "createdAt": "2023-11-07T05:31:56Z",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "labels": {},
        "externalId": "<string>"
      },
      "data": {
        "objectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
        "sequence": 123,
        "promptTokens": 123,
        "completionTokens": 123,
        "previousWindowContinueInstructions": "<string>"
      },
      "info": {
        "objective": {
          "id": "<string>",
          "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
          "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
          "createdAt": "2023-11-07T05:31:56Z",
          "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
          "labels": {},
          "externalId": "<string>"
        },
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

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

An objective starts with one context window. When it fills past the compaction threshold, Cadenya opens a fresh one and carries a summary forward. This endpoint is the record of that: what each window cost, and what survived the handoff. It is also the only token history that outlives the objective.

const windows = await client.objectives.listContextWindows(objectiveId, { workspaceId });

for await (const w of windows) {
  console.log(w.data.sequence, w.data.promptTokens, w.data.completionTokens);
}
// 2  3345  255
// 1  8718  478

windows := client.Objectives.ListContextWindowsAutoPaging(ctx, objectiveID,
	cadenya.ObjectiveListContextWindowsParams{WorkspaceID: cadenya.String(workspaceID)})

for windows.Next() {
	w := windows.Current()
	fmt.Println(w.Data.Sequence, w.Data.PromptTokens, w.Data.CompletionTokens)
}
// 2  3345  255
// 1  8718  478

windows = cadenya.objectives.list_context_windows(objective_id, workspace_id: workspace_id)

windows.auto_paging_each do |w|
  puts [w.data.sequence, w.data.prompt_tokens, w.data.completion_tokens].join("  ")
end
# 2  3345  255
# 1  8718  478

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

Windows come back newest first, and the endpoint returns at most the last five. A long objective that compacted a dozen times has lost the early ones.

Reading a compaction

That output is a real compaction, and it tells the whole story. Window 1 grew to 8,718 prompt tokens. It crossed the threshold, so Cadenya summarized it, opened window 2, and window 2 restarted at 3,345 prompt tokens. The summary itself is on the new window, as previousWindowContinueInstructions:

const [newest] = (await client.objectives.listContextWindows(objectiveId, { workspaceId })).items;

console.log(newest.data.previousWindowContinueInstructions);
// ## Conversation Summary
//
// **Task:** User requested a generated fake name and address.
//
// **Actions Taken:**
// 1. Qu...

The first window’s previousWindowContinueInstructions is empty, because nothing preceded it. That is how you tell the original window from a compacted one: sequence: 1 with no instructions. Read the summary when an agent seems to forget something mid-objective. Compaction is lossy by design, and this field is exactly what it chose to keep. If the thing the agent lost is missing here, tune summarization.instructions on the variation.

Use it for the post-mortem

Objective diagnostics gives a much richer breakdown, per component, but only while the objective is live. Every terminal objective reports zeros there. Context windows persist. The same STATE_TIMED_OUT objective that reports inputTokens: 0 from diagnostics still reports promptTokens: 34653 here.

Question	Endpoint
Where is my window going, right now?	Diagnostics
What did this finished run cost?	This one
How many times did it compact?	This one, or `info.totalContextWindows`
What did compaction throw away?	`previousWindowContinueInstructions`

const objective = await client.objectives.retrieve(objectiveId, { workspaceId, includeInfo: true });
console.log(objective.info?.totalContextWindows);   // 2
console.log(objective.info?.currentContextWindowId); // objwin_...

totalContextWindows counts every window, including any the five-window cap has aged out of this list.

What each window carries

Field	What it means
`sequence`	1 for the original window, incrementing on each compaction.
`promptTokens`	Input tokens sent to the model across this window’s turns.
`completionTokens`	Tokens the model produced.
`previousWindowContinueInstructions`	The summary carried in from the window before. Empty on `sequence: 1`.

Sum promptTokens and completionTokens across windows and multiply by the model’s inputPricePerMillionTokens and outputPricePerMillionTokens to price a run. That is the closest thing to a per-objective invoice the API offers.

Compaction itself costs a model call: the summarizer runs on the variation’s own model, and its usage is recorded as an iteration. A window’s promptTokens is what the agent spent, not what compaction spent producing the summary that opened it.

Get objective diagnostics

The live, component-by-component breakdown of the current window.

Create a variation

triggerThreshold, summarization instructions, and tool result clearing.

Compaction

Why an objective compacts instead of failing.

List models

The per-million-token prices you need to turn tokens into dollars.

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 objective ID to return windows for

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Query Parameters

limit

integer<int32>

Maximum number of results to return

cursor

string

Pagination cursor from previous response

includeInfo

boolean

When set to true you may use more of your alloted API rate-limit

labels

string

Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).

Response

ListObjectiveContextWindowsResponse is the response to a ListObjectiveContextWindowsRequest

items

object[]

Show child attributes

pagination

object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.

Show child attributes

​Reading a compaction

​Use it for the post-mortem

​What each window carries

​Related

Get objective diagnostics

Create a variation

Compaction

List models

Authorizations

Path Parameters

Query Parameters

Response

Reading a compaction

Use it for the post-mortem

What each window carries

Related