> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Execution Stats

> Retrieve aggregated execution statistics for your tools, grouped and filtered by integration, status, date, and more. Maximum date range is 90 days.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Query Parameters

**Grouping**

**group\_by** `string`

Comma-separated list of fields to group results by. Supported values: `integration`, `action`, `status`, `tool_id`, `resource_id`, `error_type`, `date`.

Example: `group_by=integration,status`

**Metrics**

**metrics** `string`

Comma-separated list of metrics to compute. Use `"count"` for total execution count, or `"field:avg"` for averages.

Supported aggregate fields: `execution_time_ms`, `input_size_kb`, `output_size_kb`.

Defaults to `"count"`.

Example: `metrics=count,execution_time_ms:avg`

**Date Range**

**period** `string`

Preset time period. Allowed values: `"today"`, `"week"`, `"month"`. Overridden by `start_date`/`end_date` if both are provided.

**start\_date** `string`

Start of the date range (ISO 8601). Maximum range is 90 days from `end_date`.

**end\_date** `string`

End of the date range (ISO 8601). Maximum range is 90 days from `start_date`.

**Filters**

**tool\_id** `string`

Filter stats to a specific tool ID.

**resource\_id** `string`

Filter stats to a specific resource ID.

**integration** `string`

Filter by integration key.

**action** `string`

Filter by action name.

**status** `string`

Filter by execution status. Allowed values: `"success"`, `"error"`.

**error\_type** `string`

Filter by error type.

**call\_id** `string`

Filter to a specific call ID.

**limit** `number`

Maximum number of groups to return. Minimum `1`, maximum `1000`. Defaults to `50`.

### Response

**results** `array`

Array of aggregated result objects. Each entry contains the grouped dimensions and the requested metric values.

**result entry**

**integration** `string`

Integration key (present when grouped by `integration`).

**action** `string`

Action name (present when grouped by `action`).

**status** `string`

Execution status (present when grouped by `status`).

**tool\_id** `string`

Tool ID (present when grouped by `tool_id`).

**date** `string`

Date string (present when grouped by `date`).

**count** `number`

Total execution count (present when `count` is in `metrics`).

**execution\_time\_ms\_avg** `number`

Average execution time in ms (present when `execution_time_ms:avg` is in `metrics`).

**input\_size\_kb\_avg** `number`

Average input size in KB (present when `input_size_kb:avg` is in `metrics`).

**output\_size\_kb\_avg** `number`

Average output size in KB (present when `output_size_kb:avg` is in `metrics`).

**meta** `object`

Metadata about the query that was executed.

```json Request theme={null}
GET /v2/tools/logs/stats?group_by=integration,status&metrics=count,execution_time_ms:avg&period=week
```

```json Response (Success) theme={null}
{
  "results": [
    {
      "integration": "slack",
      "status": "success",
      "count": 142,
      "execution_time_ms_avg": 318.5
    },
    {
      "integration": "slack",
      "status": "error",
      "count": 3,
      "execution_time_ms_avg": 10000.0
    }
  ],
  "meta": {
    "group_by": ["integration", "status"],
    "metrics": ["count", "execution_time_ms:avg"],
    "period": "week"
  }
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.