List objective tool calls

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 objectiveToolCall of client.objectives.toolCalls.list(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
)) {
  console.log(objectiveToolCall.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.tool_calls.list(
    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.ToolCalls.List(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveToolCallListParams{
			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.tool_calls.list(
  "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}/tool_calls",
  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": {
        "callable": {
          "type": "tool",
          "tool": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "createdAt": "2023-11-07T05:31:56Z",
            "externalId": "<string>",
            "labels": {},
            "updatedAt": "2023-11-07T05:31:56Z"
          }
        },
        "arguments": {},
        "memo": "<string>",
        "statusChangedBy": {
          "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>"
          }
        },
        "resolvedSecrets": [
          {
            "key": "<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>"
          }
        },
        "tool": {
          "id": "<string>",
          "name": "<string>"
        },
        "toolSet": {
          "id": "<string>",
          "name": "<string>"
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

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

GET

workspaces

{workspaceId}

objectives

{objectiveId}

tool_calls

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 objectiveToolCall of client.objectives.toolCalls.list(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
)) {
  console.log(objectiveToolCall.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.tool_calls.list(
    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.ToolCalls.List(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveToolCallListParams{
			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.tool_calls.list(
  "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}/tool_calls",
  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": {
        "callable": {
          "type": "tool",
          "tool": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "createdAt": "2023-11-07T05:31:56Z",
            "externalId": "<string>",
            "labels": {},
            "updatedAt": "2023-11-07T05:31:56Z"
          }
        },
        "arguments": {},
        "memo": "<string>",
        "statusChangedBy": {
          "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>"
          }
        },
        "resolvedSecrets": [
          {
            "key": "<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>"
          }
        },
        "tool": {
          "id": "<string>",
          "name": "<string>"
        },
        "toolSet": {
          "id": "<string>",
          "name": "<string>"
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "<string>"
  }
}

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

One row per tool invocation, carrying the arguments the model chose and where the call stands. This is what a bare tool harness polls, and what an approval UI reads.

const calls = await client.objectives.toolCalls.list(objectiveId, { workspaceId });

for await (const call of calls) {
  const c = call.data.callable;
  console.log(c.type === 'tool' ? c.tool.name : c.type, call.executionStatus);
}
// GenerateFake     TOOL_CALL_EXECUTION_STATUS_COMPLETED
// GenerateFake     TOOL_CALL_EXECUTION_STATUS_COMPLETED
// GetFakerOptions  TOOL_CALL_EXECUTION_STATUS_COMPLETED
// GenerateFake     TOOL_CALL_EXECUTION_STATUS_COMPLETED
// GenerateFake     TOOL_CALL_EXECUTION_STATUS_COMPLETED

calls := client.Objectives.ToolCalls.ListAutoPaging(ctx, objectiveID,
	cadenya.ObjectiveToolCallListParams{WorkspaceID: cadenya.String(workspaceID)})

for calls.Next() {
	call := calls.Current()
	fmt.Println(call.Data.Callable.Tool.Name, call.ExecutionStatus)
}
// GenerateFake     TOOL_CALL_EXECUTION_STATUS_COMPLETED
// GetFakerOptions  TOOL_CALL_EXECUTION_STATUS_COMPLETED

calls = cadenya.objectives.tool_calls.list(objective_id, workspace_id: workspace_id)

calls.auto_paging_each do |call|
  puts [call.data.callable.tool&.name, call.execution_status].join("  ")
end
# GenerateFake     TOOL_CALL_EXECUTION_STATUS_COMPLETED
# GetFakerOptions  TOOL_CALL_EXECUTION_STATUS_COMPLETED

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

Two statuses, and they sit on the call

status answers “may it run.” executionStatus answers “did it.” Both are top-level, not inside data, which is easy to get wrong because everything else lives under data.

call.status;           // TOOL_CALL_STATUS_AUTO_APPROVED
call.executionStatus;  // TOOL_CALL_EXECUTION_STATUS_COMPLETED
call.data.arguments;   // { "name": "company.name" }

A tool with requiresApproval: false reads AUTO_APPROVED before it ever runs. One behind approval sits at TOOL_CALL_STATUS_WAITING_FOR_APPROVAL until a person decides, then moves to APPROVED or DENIED. Both filter server-side:

const parked = await client.objectives.toolCalls.list(objectiveId, {
  workspaceId,
  executionStatus: 'TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT',
});

That one filter is the bare-tool harness: every call waiting on your code, and nothing else.

The list omits results. Get by ID returns them.

A list row holds callable, arguments, and the two statuses. It carries no result, so paging a long objective stays cheap. Get a tool call returns the same call plus result, at the top level rather than under data, with no includeInfo needed. The response schema is named ObjectiveToolCallWithResult, which tells you where the line falls.

const call = await client.objectives.toolCalls.retrieve(toolCallId, { workspaceId, objectiveId });

console.log(JSON.stringify(call.result));
// {"content":[{"text":{"text":"{\"name\":\"company.name\",\"value\":\"Weissnat, Weissnat and Weissnat\"}"}}]}

You want	Read
What was the tool called with?	This endpoint, `data.arguments`
Was it approved, and did it run?	This endpoint, `status` and `executionStatus`
What did it return?	Get a tool call, `result`, or the `toolResult` event from List objective events

`callable` names what was invoked

A discriminated union, like an assignment: type reads tool, agent, or cadenyaProvidedTool, and the payload sits under the matching key.

const c = call.data.callable;
switch (c.type) {
  case 'tool':                c.tool.name;                // 'GenerateFake'
  case 'agent':               c.agent.name;               // a sub-agent
  case 'cadenyaProvidedTool': c.cadenyaProvidedTool.name; // 'get_memory'
}

Unlike the toolCalled event, which ships a built-in’s name empty, this endpoint fills it in. When a transcript rendered from the stream hits an unnamed built-in, this is where its name lives.

`resolvedSecrets` gives the key and source, never the value

Each entry gives the secret’s key and which scope supplied it, so you can prove a per-user token overrode a workspace credential without the value ever crossing the wire.

{ "key": "EXAMPLE_TOKEN", "source": "RESOLVED_SECRET_SOURCE_OBJECTIVE" }

Sources rank RESOLVED_SECRET_SOURCE_OBJECTIVE, then _TOOLSET, then _WORKSPACE: the narrowest scope wins. The array is empty when the tool needs no secrets.

The harness loop

const parked = await client.objectives.toolCalls.list(objectiveId, {
  workspaceId,
  executionStatus: 'TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT',
});

for await (const call of parked) {
  const result = await runItYourself(call.data.arguments);

  await client.objectives.toolCalls.setContent(call.metadata.id, {
    workspaceId,
    objectiveId,
    content: [{ type: 'text', text: { text: JSON.stringify(result) } }],
  });
}

Poll, execute, answer. Cadenya never opens a connection into your network.

Set tool call content

Answer a parked call. Your code is the tool runtime.

Approve a tool call

Where WAITING_FOR_APPROVAL gets resolved.

Get a tool call

The same call, plus its result.

Store and use secrets

What resolvedSecrets.source is telling you.

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 tool calls for

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Query Parameters

limit

integer<int32>

Maximum number of results to return

cursor

string

Pagination cursor from previous response

status

enum<string>

Filter by tool call status

Available options:

TOOL_CALL_STATUS_UNSPECIFIED,

TOOL_CALL_STATUS_AUTO_APPROVED,

TOOL_CALL_STATUS_WAITING_FOR_APPROVAL,

TOOL_CALL_STATUS_APPROVED,

TOOL_CALL_STATUS_DENIED

includeInfo

boolean

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

executionStatus

enum<string>

Filter by tool call execution status. Useful for reverse-harness polling of bare tool calls waiting for externally supplied content (TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT).

Available options:

TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED,

TOOL_CALL_EXECUTION_STATUS_PENDING,

TOOL_CALL_EXECUTION_STATUS_RUNNING,

TOOL_CALL_EXECUTION_STATUS_COMPLETED,

TOOL_CALL_EXECUTION_STATUS_ERRORED,

TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT

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

​Two statuses, and they sit on the call

​The list omits results. Get by ID returns them.

​callable names what was invoked

​resolvedSecrets gives the key and source, never the value

​The harness loop

​Related

Set tool call content

Approve a tool call

Get a tool call

Store and use secrets

Authorizations

Path Parameters

Query Parameters

Response

Two statuses, and they sit on the call

The list omits results. Get by ID returns them.

`callable` names what was invoked

`resolvedSecrets` gives the key and source, never the value

The harness loop

Related