# Tool Call Insights

Retrieve per-tool call volume, latency, and health for a business.

Returns how each of your tools performed over a date range: how many conversations called it, how long it took to respond, and how often it succeeded, failed, or timed out. Only tools you supplied are reported. Figures are rolled up once a day, so the most recent day may still be incomplete. This endpoint allows 1,000 requests per hour for each app and `entity_id` pair. Once that is exhausted, further requests return `429` until the limit resets.

## Base URL

| URL | Description |
|-----|-------------|
| https://api.facebook.com/{entity_id}/insights/tool_calls |  |

## Authorization

This API requires:

any of the following
  - Capability: bizai_wa_enterprise_api_3p_access
  - Permission: whatsapp_business_messaging
  - Permission: instagram_basic

## APIs

| Method | Endpoint |
|--------|----------|
| GET | [/](#get) |

<jumplink id="get"></jumplink>
## GET /

Get tool call insights

Retrieve per-tool call volume, latency, and health for the specified date range


### Header Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| X-API-Version | "2.0.0" |  |  |

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| entity_id | string | ✓ | The business asset whose tool call insights to return. |

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| start_date | string | ✓ | First day to include, as YYYY-MM-DD in the business time zone. The boundary is inclusive. |
| end_date | string | ✓ | Last day to include, as YYYY-MM-DD in the business time zone. The boundary is inclusive. start_date and end_date may span at most 30 days, counting both the first and last day. |
| tool_name | string |  | Return only this tool, named as you registered it. Omit to get every tool that was called in the range. |

### Responses

**200**

The tool call insights for the requested range


**Content Type**: `application/json`

**Schema**: object

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| data | array of [BizAIOmniChannelToolCallInsights](#bizaiomnichanneltoolcallinsights) | ✓ | One row per tool called in the range, busiest first. Empty when no tool of yours was called. |

**400**

Bad request

**Content Type**: `application/json`

**Schema**: [StandardError](#standarderror)

**404**

Not found

**Content Type**: `application/json`

**Schema**: [StandardError](#standarderror)

**401**

Unauthorized

**Content Type**: `application/json`

**Schema**: [StandardError](#standarderror)

**403**

Forbidden

**Content Type**: `application/json`

**Schema**: [StandardError](#standarderror)

**429**

Too many requests

**Content Type**: `application/json`

**Schema**: [StandardError](#standarderror)

**500**

Server error

**Content Type**: `application/json`

**Schema**: [StandardError](#standarderror)


# Components

## Schemas

<jumplink id="bizaiomnichanneltoolcallinsights"></jumplink>
### BizAIOmniChannelToolCallInsights

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| tool_name | string | ✓ | The tool these figures cover, as you named it when you registered it. Only tools you supplied are reported. |
| thread_count | integer | ✓ | Conversations that called this tool, counted once per day and summed over the range. A conversation that called the tool on three separate days counts three times. |
| avg_latency_ms | number |  | Mean time the tool took to respond, in milliseconds, over every call in the range that was timed. Null when none were timed. |
| success_rate | number |  | Share of calls that returned without an error, between 0 and 1. Null when no call in the range reported an outcome. |
| error_rate | number |  | Share of calls that returned an error, between 0 and 1. Timeouts are errors, so they are included here as well as in timeout_rate. Null when no call in the range reported an outcome. |
| timeout_rate | number |  | Share of calls that timed out, between 0 and 1. A subset of error_rate. Null when no call in the range reported an outcome. |

<jumplink id="standarderror"></jumplink>
### StandardError

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| detail | string | ✓ |  |
| status | integer |  |  |
| title | string | ✓ |  |
| type | string |  |  |

## Authentication

| Method | How to send it |
|--------|----------------|
| Authorization header | `Authorization: Bearer {access-token}` |

### Global Authentication Requirements

All endpoints require: `Authorization: Bearer {access-token}`