Tool Calls

Tool calls represent individual tool invocations within a session. They track the input, output, and status of each tool execution.

Tool Calls object

Attributes

object

String

String representing the object's type

id

String

Unique tool call identifier

tool_key

String

The key identifying the tool that was called

type

String

The type of the tool call

status

String

Current status of the tool call

source

String

Source of the tool call

transport

String

Transport protocol used

session_id

String

Parent session ID

message_id

String

Associated session message ID

session_provider_id

StringNullable

Session provider ID

connection_id

StringNullable

Session connection ID

provider_run_id

StringNullable

Provider run ID

tool

ObjectNullable

The tool definition that was called

input

ObjectNullable

Input data passed to the tool call

output

ObjectNullable

Output data returned from the tool call

error

ObjectNullable

Error details if the tool call failed

metadata

ObjectNullable

Custom key-value metadata

created_at

Date

Timestamp when created

{
  "object": "session.tool_call",
  "id": "tcl_8hJkLmNpQrStUvWx",
  "tool_key": "create_issue",
  "type": "tool_call",
  "status": "waiting_for_response",
  "source": "client",
  "transport": "mcp",
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "message_id": "smg_3cDeFgHjKlMnPqRs",
  "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
  "connection_id": "scn_2bCdEfGhJkLmNpQr",
  "provider_run_id": "prn_8hJkLmNpQrStUvWx",
  "tool": {},
  "input": {},
  "output": {},
  "error": {},
  "metadata": {
    "source": "manual"
  },
  "created_at": "2025-09-15T10:30:00.000Z"
}

List all tool calls

Returns a paginated list of tool calls across all sessions.

Query Parameters

limit

NumberOptional

Maximum number of items to return (1-100)

after

StringOptional

Return items after this ID

before

StringOptional

Return items before this ID

cursor

StringOptional

Pagination cursor from a previous response

order

EnumOptional

Sort order for results

session_template_id

UnionOptional

Filter by session template ID(s)

session_provider_id

UnionOptional

Filter by session provider ID(s)

provider_id

UnionOptional

Filter by provider ID(s)

provider_deployment_id

UnionOptional

Filter by provider deployment ID(s)

provider_config_id

UnionOptional

Filter by provider config ID(s)

provider_auth_config_id

UnionOptional

Filter by provider auth config ID(s)

tool_id

UnionOptional

Filter by tool ID(s)

GEThttp://api.metorial.com/tool-calls
curl -X GET "https://api.metorial.com/tool-calls" \
  -H "Authorization: Bearer metorial_sk_..."

Get tool call

Retrieves a specific tool call by ID.

URL Parameters

tool_call_id

String

The unique identifier for the tool_call

GEThttp://api.metorial.com/tool-calls/:tool_call_id
curl -X GET "https://api.metorial.com/tool-calls/too_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

List tool calls

Returns a paginated list of tool calls for a session.

URL Parameters

session_id

String

The unique identifier for the session

Query Parameters

limit

NumberOptional

Maximum number of items to return (1-100)

after

StringOptional

Return items after this ID

before

StringOptional

Return items before this ID

cursor

StringOptional

Pagination cursor from a previous response

order

EnumOptional

Sort order for results

session_template_id

UnionOptional

Filter by session template ID(s)

session_provider_id

UnionOptional

Filter by session provider ID(s)

provider_id

UnionOptional

Filter by provider ID(s)

provider_deployment_id

UnionOptional

Filter by provider deployment ID(s)

provider_config_id

UnionOptional

Filter by provider config ID(s)

provider_auth_config_id

UnionOptional

Filter by provider auth config ID(s)

tool_id

UnionOptional

Filter by tool ID(s)

GEThttp://api.metorial.com/sessions/:session_id/tool-calls
curl -X GET "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY/tool-calls" \
  -H "Authorization: Bearer metorial_sk_..."

Get tool call

Retrieves a specific tool call for a session.

URL Parameters

session_id

String

The unique identifier for the session

tool_call_id

String

The unique identifier for the tool_call

GEThttp://api.metorial.com/sessions/:session_id/tool-calls/:tool_call_id
curl -X GET "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY/tool-calls/too_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create tool call

Creates a new tool call in a session by invoking a specific tool.

URL Parameters

session_id

String

The unique identifier for the session

Request Body

tool_id

String

The ID of the tool to call

input

Object

Input data to pass to the tool

metadata

ObjectOptional

Optional metadata for the tool call

POSThttp://api.metorial.com/sessions/:session_id/tool-calls
curl -X POST "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY/tool-calls" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "tool_id": "example_tool_id",
  "input": {},
  "metadata": {}
}'