Stream 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
});

const objectiveEvent = await client.objectives.streamEvents('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
)
for objective in client.objectives.stream_events(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
):
  print(objective)

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"),
	)
	stream := client.Objectives.StreamEventsStreaming(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveStreamEventsParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	for stream.Next() {
		fmt.Printf("%+v\n", stream.Current())
	}
	err := stream.Err()
	if err != nil {
		panic(err.Error())
	}
}

require "cadenya"

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

objective_event = cadenya.objectives.stream_events(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(objective_event)

<?php

$curl = curl_init();

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

{
  "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"
}

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

GET

workspaces

{workspaceId}

objectives

{objectiveId}

events:stream

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 objectiveEvent = await client.objectives.streamEvents('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
)
for objective in client.objectives.stream_events(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
):
  print(objective)

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"),
	)
	stream := client.Objectives.StreamEventsStreaming(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveStreamEventsParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	for stream.Next() {
		fmt.Printf("%+v\n", stream.Current())
	}
	err := stream.Err()
	if err != nil {
		panic(err.Error())
	}
}

require "cadenya"

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

objective_event = cadenya.objectives.stream_events(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(objective_event)

<?php

$curl = curl_init();

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

{
  "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"
}

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

An objective runs in the background. This endpoint is how you watch it: a server-sent event stream that pushes each event the moment it lands, so you can render a live transcript instead of polling. The endpoint takes no query parameters. Connect, and you get events from now forward.

Read the stream

The SDKs hand you an iterator and skip the transport bookkeeping.

const stream = await client.objectives.streamEvents(objective.metadata.id, { workspaceId });

events:
for await (const event of stream) {
  const data = event.data;

  switch (data.type) {
    case 'assistantMessage':
      process.stdout.write(data.assistantMessage.content ?? '');
      break;
    case 'toolCalled': {
      // CallableTool is a union. Its type field names the variant.
      const called = data.toolCalled.tool;
      const name =
        called?.type === 'tool' ? called.tool.name :     // a tool from a tool set
        called?.type === 'agent' ? called.agent.name :   // a sub-agent
        '(built-in)';                                    // get_memory, tool_search: name arrives blank
      console.log('calling', name, data.toolCalled.arguments);
      break;
    }
    case 'finalized':
    case 'cancelled':
    case 'timedOut':
    case 'error':
      break events;
  }
}

stream := client.Objectives.StreamEventsStreaming(ctx, objectiveID,
	cadenya.ObjectiveStreamEventsParams{WorkspaceID: cadenya.String(workspaceID)})
defer stream.Close()

for stream.Next() {
	event := stream.Current()

	switch data := event.Data.AsAny().(type) {
	case cadenya.ObjectiveEventDataAssistantMessage:
		fmt.Print(data.AssistantMessage.Content)
	case cadenya.ObjectiveEventDataToolCalled:
		fmt.Println("tool called", data.ToolCalled.ToolCallID)
	case cadenya.ObjectiveEventDataError:
		log.Fatal(data.Error.Message)
	case cadenya.ObjectiveEventDataFinalized,
		cadenya.ObjectiveEventDataCancelled,
		cadenya.ObjectiveEventDataTimedOut:
		return
	}
}
if err := stream.Err(); err != nil {
	log.Fatal(err)
}

stream = cadenya.objectives.stream_events(objective.metadata.id, workspace_id: workspace_id)

stream.each do |event|
  case event.data&.type
  when :assistantMessage
    print event.data.assistant_message&.content
  when :toolCalled
    # CallableTool is a union. Built-ins (get_memory, tool_search) arrive with a blank name.
    called = event.data.tool_called&.tool
    name = called&.tool&.name || called&.agent&.name || "(built-in)"
    puts "calling #{name} #{event.data.tool_called&.arguments}"
  when :finalized, :cancelled, :timedOut, :error
    break # break aborts the underlying request for you
  end
end

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

# event: open
# data: {"time":"2026-07-08T16:34:20Z"}
#
# id: objevt_01KX19974R5KKN6P0VFFXHQK3A
# event: assistantMessage
# data: {"metadata":{...},"data":{"type":"assistantMessage",...}}

In TypeScript, ObjectiveEvent.data is a discriminated union. Each case narrows data to the matching event interface, so the corresponding payload is available without a cast.

The stream never closes on its own. Reaching STATE_FINALIZED does not end the connection. It stays open, emitting a ping every 15 seconds, until the load balancer severs it at 10 minutes.Break on the terminal event type, never on end-of-stream. A loop with no break holds a connection for ten minutes after the objective finishes, and a client that reconnects whenever the stream ends reconnects forever on a completed objective.

What arrives on the wire

Each event frame carries three SSE fields: id is the event’s ULID, event is the event type (assistantMessage, toolCalled, …), and data is the JSON ObjectiveEvent. Two control frames carry no id and are not objective events:

open, once, when the stream commits. Its arrival means the connection is live and the status code is settled.
ping, every 15 seconds, to keep intermediaries from closing an idle connection.

The SDKs drop open and ping before they reach your loop. If you read the raw stream, skip them yourself: they do not parse as an ObjectiveEvent.

Tool results are stripped

This is the one surprise worth internalizing. On the stream, toolResult and toolError events carry only the toolCallId. The content is cleared, because a tool that returns a megabyte of JSON would otherwise push it through every open connection.

Streamed

{ "type": "toolResult",
  "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR" } }

Same event from listEvents

{ "type": "toolResult",
  "toolResult": { "toolCallId": "toolcall_01KX19F3FMY79A8TNFNP6C9VRR",
                  "result": { "content": [{ "type": "text", "text": { "text": "{\"options\":[...]}" } }] } } }

Every other event type passes through whole. When you need a result body, fetch the call by ID with Get a tool call, which returns result at the top level, or read the event back from List objective events.

Built-in tool calls arrive unnamed

toolCalled.tool is a discriminated union: its type field reads tool for a tool from a tool set, agent for a sub-agent, or cadenyaProvidedTool for a built-in such as get_memory or tool_search, and the payload sits under the matching key. Switch on type, never reach through tool.tool. The built-in case carries an opaque cpt_... id and an empty name. arguments tells you what it did ({"memoryKey": "policies/us/refunds"}), and Get a tool call returns the same call with callable.cadenyaProvidedTool.name filled in.

Resume where you left off

Send the SSE Last-Event-ID header with the last event ULID you processed. Cadenya replays the gap from durable storage, then switches you to the live feed, deduplicating the overlap. Omit the header and you get events from now, with no replay of anything the objective already emitted.

let lastEventId: string | undefined;

streaming:
while (true) {
  const stream = await client.objectives.streamEvents(objectiveId, {
    workspaceId,
  }, {
    headers: lastEventId ? { 'Last-Event-ID': lastEventId } : undefined,
  });

  for await (const event of stream) {
    lastEventId = event.metadata.id; // remember before you handle it
    if (isTerminal(event.data.type)) break streaming;
    handle(event);
  }
  // Fell out of the loop without a terminal event: the connection dropped.
  // Reconnect from lastEventId. Nothing is lost.
}

curl -N "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/events:stream" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: objevt_01KX1993PV6MHJ10BS2VS01FM8"

Neither SDK reconnects for you, and neither tracks the last event ID. The loop above is the pattern to copy. A single connection lives at most 10 minutes by design, so any objective that runs longer requires this reconnect loop.

An unusable Last-Event-ID fails before the stream commits, so it comes back as a real HTTP status rather than a mid-stream error. Once open arrives the status is committed, and any later failure ends the connection with no status to read.

Every event type

Eighteen types. data is a discriminated union: type names the variant, and the payload sits under a key with the same name.

`type`	Meaning
`userMessage`	A turn from you, including the first one.
`assistantMessage`	The agent said something.
`reasoning`	A model exposed reasoning text or a provider-generated reasoning summary.
`toolCalled`	The agent invoked a tool.
`toolResult`	The tool returned. Stripped on the stream.
`toolError`	The tool failed. Stripped on the stream.
`toolApprovalRequested`	Work is parked pending approval.
`toolApproved`	Someone approved the call.
`toolDenied`	Someone denied it.
`memoryRead`	Defined, but not observed firing. A `get_memory` call arrives as `toolCalled`.
`contextWindowCompacted`	The window filled and compaction ran.
`subAgentSpawned`	The agent delegated to a sub-objective.
`subAgentUpdated`	A sub-objective changed status.
`notice`	Informational.
`finalized`	Terminal. The objective produced its output.
`cancelled`	Terminal. A caller cancelled it.
`timedOut`	Terminal. It hit the inactivity timeout.
`error`	Terminal. It failed.

The four terminal types are the ones your loop must watch for.

An objective that answers and waits for your next turn never emits a terminal event. It sits in STATE_WAITING, and the stream stays open. Break on the last assistantMessage when you are driving a conversation rather than waiting on an output.

Streaming or webhooks

Both carry the same events. They fail differently, and that is how you choose. Stream when a human is watching: a chat UI, a live transcript, a progress log. It is a live tail with no delivery guarantee beyond the Last-Event-ID resume path, and it needs a process holding a connection open. Webhook when a machine is reacting: kicking off a job, writing to a database, paging someone. Deliveries retry, and each one records its status, attempt count, and response, so you can audit what your endpoint received. Reach for both on the same objective when a person watches the work while a system records it.

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

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Response

A stream of Server-Sent Events

metadata

object

required

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

Show child attributes

data

object

required

Show child attributes

contextWindowId

string

Example:

"objwin_01HXKD2E5NQM3T9AYWCFN7BSTR"

info

object

Show child attributes

duration

string

read-only

Elapsed time of the work this event records, when it is known at write time (e.g. assistant message generation, tool execution for result/error events). Unset means the event is instantaneous or the duration is not measurable. Serialized as a canonical duration string (e.g. "4.1s"). Always set together with started_at.

Pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$

startedAt

string<date-time>

read-only

When the work this event records began. Set together with duration, so the work interval is [started_at, started_at + duration]. The event's created_at remains the time the event was persisted.

​Read the stream

​What arrives on the wire

​Tool results are stripped

​Built-in tool calls arrive unnamed

​Resume where you left off

​Every event type

​Streaming or webhooks

Authorizations

Path Parameters

Response

Read the stream

What arrives on the wire

Tool results are stripped

Built-in tool calls arrive unnamed

Resume where you left off

Every event type

Streaming or webhooks