Get a tool call

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 objectiveToolCallWithResult = await client.objectives.toolCalls.retrieve(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  'toolcall_01HXKD2E5NQM3T9AYWCFTANFGV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
);

console.log(objectiveToolCallWithResult.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
)
objective_tool_call_with_result = client.objectives.tool_calls.retrieve(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    tool_call_id="toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(objective_tool_call_with_result.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"),
	)
	objectiveToolCallWithResult, err := client.Objectives.ToolCalls.Get(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
		cadenya.ObjectiveToolCallGetParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveToolCallWithResult.Data)
}

require "cadenya"

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

objective_tool_call_with_result = cadenya.objectives.tool_calls.retrieve(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  "toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(objective_tool_call_with_result)

cadenya objectives:tool-calls retrieve \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
  --tool-call-id toolcall_01HXKD2E5NQM3T9AYWCFTANFGV

<?php

$curl = curl_init();

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

HttpResponse<String> response = Unirest.get("https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}")
  .header("Authorization", "Bearer <token>")
  .asString();

{
  "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>"
    }
  },
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "text": "<string>"
        }
      }
    ]
  },
  "resolvedSecrets": [
    {
      "key": "<string>"
    }
  ]
}

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

GET

workspaces

{workspaceId}

objectives

{objectiveId}

tool_calls

{toolCallId}

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 objectiveToolCallWithResult = await client.objectives.toolCalls.retrieve(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  'toolcall_01HXKD2E5NQM3T9AYWCFTANFGV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
);

console.log(objectiveToolCallWithResult.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
)
objective_tool_call_with_result = client.objectives.tool_calls.retrieve(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    tool_call_id="toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(objective_tool_call_with_result.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"),
	)
	objectiveToolCallWithResult, err := client.Objectives.ToolCalls.Get(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
		cadenya.ObjectiveToolCallGetParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveToolCallWithResult.Data)
}

require "cadenya"

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

objective_tool_call_with_result = cadenya.objectives.tool_calls.retrieve(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  "toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(objective_tool_call_with_result)

cadenya objectives:tool-calls retrieve \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
  --tool-call-id toolcall_01HXKD2E5NQM3T9AYWCFTANFGV

<?php

$curl = curl_init();

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

HttpResponse<String> response = Unirest.get("https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}")
  .header("Authorization", "Bearer <token>")
  .asString();

{
  "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>"
    }
  },
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "text": "<string>"
        }
      }
    ]
  },
  "resolvedSecrets": [
    {
      "key": "<string>"
    }
  ]
}

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

Listing tool calls gives you arguments and status. Fetching one gives you what the tool returned.

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

const callable = call.data.callable;
console.log(callable.type);                   // 'tool'
if (callable.type === 'tool') {
  console.log(callable.tool.name);            // 'GenerateFake'
}
console.log(call.executionStatus);            // 'TOOL_CALL_EXECUTION_STATUS_COMPLETED'
console.log(JSON.stringify(call.result));
// {"content":[{"type":"text","text":{"text":"{\"name\":\"company.name\",\"value\":\"Weissnat, Weissnat and Weissnat\"}"}}]}

call, err := client.Objectives.ToolCalls.Get(ctx, objectiveID, toolCallID,
	cadenya.ObjectiveToolCallGetParams{WorkspaceID: cadenya.String(workspaceID)})

fmt.Println(call.Data.Callable.Tool.Name) // GenerateFake
fmt.Println(call.ExecutionStatus)         // TOOL_CALL_EXECUTION_STATUS_COMPLETED
fmt.Printf("%+v\n", call.Result)

call = cadenya.objectives.tool_calls.retrieve(
  tool_call_id,
  workspace_id: workspace_id,
  objective_id: objective_id
)

puts call.data.callable.tool&.name # GenerateFake
puts call.execution_status         # TOOL_CALL_EXECUTION_STATUS_COMPLETED
puts call.result

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

`result` sits at the top level

Not under data, where arguments and callable live. The response schema is named ObjectiveToolCallWithResult, and that name is the whole distinction from the list.

list item      →  metadata, data, status, executionStatus, info
get by id      →  metadata, data, status, executionStatus, info, result, resolvedSecrets

No includeInfo is needed. The result hydrates on every fetch, which is why the list leaves it out: paging a long objective stays cheap, and you pay for a body only when a user expands one. result.content is the same block list a bare tool submits: each block’s type reads text, image, or audio, with the payload under the matching key. Media comes back as a signed URL on the way out, even though it goes in as base64.

Three ways to reach a result body

Path	When
This endpoint	A user expanded one call in a UI
`toolResult` event from List objective events	Rendering a whole transcript
The event stream	Never. Results are stripped to a bare `toolCallId`

The stream omits bodies so a tool returning a megabyte of JSON does not push it through every open connection. That makes this endpoint the natural companion to a live UI: stream the timeline, fetch the body on click.

It resolves built-in tool names

The toolCalled event ships cadenyaProvidedTool.name empty. Here it is populated:

if (call.data.callable.type === 'cadenyaProvidedTool') {
  call.data.callable.cadenyaProvidedTool.name;  // 'get_memory'
}

So a transcript that hits an unnamed built-in can recover the name with one fetch.

`resolvedSecrets` is the secret audit trail

When a tool’s headers reference ${NAME} secrets, resolvedSecrets records which ones the call used and which scope each came from, never the value:

call.resolvedSecrets;
// [{ key: 'STRIPE_API_KEY', source: 'RESOLVED_SECRET_SOURCE_OBJECTIVE' }]

key is the reference name (not name), and source is the scope that won under the strict precedence, objective over tool set over workspace:

`source`	Resolved from
`RESOLVED_SECRET_SOURCE_OBJECTIVE`	A per-run objective secret
`RESOLVED_SECRET_SOURCE_TOOLSET`	A tool set secret
`RESOLVED_SECRET_SOURCE_WORKSPACE`	A shared workspace secret

So a call that used a customer’s per-run token reads RESOLVED_SECRET_SOURCE_OBJECTIVE, and one that fell through to the shared credential reads RESOLVED_SECRET_SOURCE_WORKSPACE. This is how you confirm the right scope won without ever seeing the secret.

Scoping is strict

The tool call must belong to the objective in the path. A valid ID under the wrong objective is a 404, not someone else’s data:

GET /objectives/{right}/tool_calls/{id}   -> 200
GET /objectives/{other}/tool_calls/{id}   -> 404
GET /objectives/{right}/tool_calls/bogus  -> 404

external_id: resolution does not apply to tool calls. They carry no external ID, so pass the toolcall_... value.

Poll for a settled status

Approve and deny resolve asynchronously, and their response reports the pre-decision state. This endpoint is where the settled one shows up.

await client.objectives.toolCalls.approve(toolCallId, { workspaceId, objectiveId });

const settled = await client.objectives.toolCalls.retrieve(toolCallId, { workspaceId, objectiveId });
settled.status;           // TOOL_CALL_STATUS_APPROVED
settled.executionStatus;  // ... then COMPLETED, once the tool runs

List tool calls

Every call, filtered by status, without result bodies.

Approve a tool call

The decision whose outcome you read here.

Set tool call content

Where a bare tool’s result.content comes from.

Stream objective events

Why the stream sends a toolCallId and no body.

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"

toolCallId

string

required

The ID of the tool call to retrieve

Example:

"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV"

Response

ObjectiveToolCallWithResult is an ObjectiveToolCall plus the content the tool returned. Returned by GetObjectiveToolCall.

metadata

object

required

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

Show child attributes

data

object

required

Show child attributes

status

enum<string>

required

Current status of the tool call

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

info

object

required

Show child attributes

executionStatus

enum<string>

required

read-only

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

result

object

The content returned by the tool. Only set once execution_status is TOOL_CALL_EXECUTION_STATUS_COMPLETED.

Show child attributes

resolvedSecrets

object[]

read-only

List of resolved secrets used by the tool call

Show child attributes

​result sits at the top level

​Three ways to reach a result body

​It resolves built-in tool names

​resolvedSecrets is the secret audit trail

​Scoping is strict

​Poll for a settled status

​Related

List tool calls

Approve a tool call

Set tool call content

Stream objective events

Authorizations

Path Parameters

Response

`result` sits at the top level

Three ways to reach a result body

It resolves built-in tool names

`resolvedSecrets` is the secret audit trail

Scoping is strict

Poll for a settled status

Related