List objective events

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 objectiveEvent of client.objectives.listEvents('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
})) {
  console.log(objectiveEvent.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_events(
    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.ListEvents(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveListEventsParams{
			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_events(
  "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}/events",
  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": {
        "type": "userMessage",
        "userMessage": {
          "content": "<string>"
        }
      },
      "contextWindowId": "objwin_01HXKD2E5NQM3T9AYWCFN7BSTR",
      "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>"
          }
        }
      },
      "duration": "<string>",
      "startedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

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

GET

workspaces

{workspaceId}

objectives

{objectiveId}

events

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 objectiveEvent of client.objectives.listEvents('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
})) {
  console.log(objectiveEvent.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_events(
    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.ListEvents(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveListEventsParams{
			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_events(
  "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}/events",
  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": {
        "type": "userMessage",
        "userMessage": {
          "content": "<string>"
        }
      },
      "contextWindowId": "objwin_01HXKD2E5NQM3T9AYWCFN7BSTR",
      "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>"
          }
        }
      },
      "duration": "<string>",
      "startedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

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

Everything an objective did is an event. This endpoint is the durable record of them, in order, with nothing withheld. Streaming is how you watch an objective work. This is how you read what it did.

const events = await client.objectives.listEvents(objectiveId, { workspaceId });

for await (const event of events) {
  console.log(event.data?.type, event.contextWindowId);
}
// userMessage       objwin_01KX18CRRNDHTFAHGA079765D9
// assistantMessage  objwin_01KX18CRRNDHTFAHGA079765D9
// toolCalled        objwin_01KX18CRRNDHTFAHGA079765D9

events := client.Objectives.ListEventsAutoPaging(ctx, objectiveID,
	cadenya.ObjectiveListEventsParams{WorkspaceID: cadenya.String(workspaceID)})

for events.Next() {
	event := events.Current()
	fmt.Println(event.Data.Type, event.ContextWindowID)
}
// userMessage       objwin_01KX18CRRNDHTFAHGA079765D9
// assistantMessage  objwin_01KX18CRRNDHTFAHGA079765D9
// toolCalled        objwin_01KX18CRRNDHTFAHGA079765D9

events = cadenya.objectives.list_events(objective_id, workspace_id: workspace_id)

events.auto_paging_each do |event|
  puts [event.data&.type, event.context_window_id].join("  ")
end
# userMessage       objwin_01KX18CRRNDHTFAHGA079765D9
# assistantMessage  objwin_01KX18CRRNDHTFAHGA079765D9
# toolCalled        objwin_01KX18CRRNDHTFAHGA079765D9

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

Events come back oldest first, which is what you want when rendering a transcript. Pass sortOrder: 'desc' for newest first.

This is where tool result bodies live

The stream strips toolResult and toolError down to a bare toolCallId, because a tool returning a megabyte of JSON would otherwise be pushed through every open connection. Here, the full body is attached.

// From the stream:
{ "type": "toolResult",
  "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR" } }

// The same event, from this endpoint:
{ "type": "toolResult",
  "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR",
                  "result": { "content": [{ "type": "text", "text": { "text": "{\"options\":[...]}" } }] } } }

So the pattern for a live UI is: stream to render the timeline as it happens, then read events (or Get a tool call) when a user expands a result.

Every event names its context window

contextWindowId sits on each event, not inside data. On an objective that has compacted, events before and after the compaction carry different window IDs, so you can group a transcript by window and show where the summary took over.

const byWindow = new Map<string, number>();
const events = await client.objectives.listEvents(objectiveId, { workspaceId });

for await (const event of events) {
  const id = event.contextWindowId ?? 'unknown';
  byWindow.set(id, (byWindow.get(id) ?? 0) + 1);
}

console.log([...byWindow.entries()]);
// [ [ 'objwin_01KX1G66RMB7ZKCN1543KY2G05', 6 ] ]

An objective that never filled its window reports a single ID, as above. One that compacted twice reports three, and the contextWindowCompacted events mark the boundaries.

No event-type filter

The endpoint takes limit, cursor, sortOrder, and includeInfo. There is no way to ask the server for only the toolCalled events, so filter on the client:

const events = await client.objectives.listEvents(objectiveId, { workspaceId });

for await (const event of events) {
  if (event.data?.type !== 'toolApprovalRequested') continue;
  console.log(event.data.toolApprovalRequested.toolCallId);
}

limit is a page size, not a cap. The SDK iterator pages transparently, so limit: 10 fetches ten per request and still yields every event. Read page.items for exactly one page. includeInfo: true adds info.createdBy, the profile that caused the event. It costs more of your rate limit and tells you nothing about the agent’s work, so skip it on a transcript render.

The seventeen event types

data is a discriminated union: type names the variant, and the payload sits under a key with the same name. { "type": "toolCalled", "toolCalled": {...} }.

`type`	The variant
`userMessage`	A turn from you
`assistantMessage`	The agent’s reply
`toolCalled`	A tool invocation
`toolResult`	What the tool returned
`toolError`	The tool failed
`toolApprovalRequested`	A call parked pending approval
`toolApproved`	Someone approved it
`toolDenied`	Someone denied it
`memoryRead`	Defined, not observed firing
`contextWindowCompacted`	Compaction ran
`subAgentSpawned`	A sub-objective started
`subAgentUpdated`	A sub-objective changed status
`notice`	Informational
`finalized`	Terminal: output produced
`cancelled`	Terminal: a caller cancelled it
`timedOut`	Terminal: inactivity timeout
`error`	Terminal: it failed

finalized.output carries the objective’s structured result, when its agent has an outputDefinition. Reading it from the event saves you a fetch.

Events or diagnostics

Both describe an objective after the fact, and they answer different questions.

Question	Endpoint
What did the agent do, in order?	This one
What arguments did a tool get, and was it approved?	List tool calls
What did a tool return?	This one, or Get a tool call
Where is the context window going?	Diagnostics, while the objective is live
What did the run cost?	Context windows

Stream objective events

The same events, live, with result bodies stripped.

Webhooks

The same events, delivered to you, with retries.

List context windows

What contextWindowId refers to, and what each window cost.

Create an objective

Where the first userMessage comes from.

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

Objective ID for filtering

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Query Parameters

limit

integer<int32>

Maximum number of results to return

cursor

string

Pagination cursor from previous response

sortOrder

string

Sort order for results (asc or desc by creation time)

includeInfo

boolean

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

windowId

string

Optional context window ID to filter events by

sinceEventId

string

Optional string to fetch events since an ID

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

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

​This is where tool result bodies live

​Every event names its context window

​No event-type filter

​The seventeen event types

​Events or diagnostics

​Related

Stream objective events

Webhooks

List context windows

Create an objective

Authorizations

Path Parameters

Query Parameters

Response

This is where tool result bodies live

Every event names its context window

No event-type filter

The seventeen event types

Events or diagnostics

Related