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

# Retrieve Per-Contact Call Performance Metrics — Shilo

> Retrieve dashboard-aligned call metrics for a single contact. Identify by Shilo UUID or external_contact_id. Filter by date and direction.

Use this endpoint to retrieve call performance metrics scoped to a single contact record in Shilo. This is particularly useful for understanding the full engagement history for a lead or client — including how many calls have been made, average call quality, and total time spent. You can identify the contact using their Shilo UUID or your own `external_contact_id`.

## Endpoint

```
GET https://api.shilo.ai/api/v1/contacts/{identifier}/metrics
```

## Authentication

Include your API key in the request header:

```
x-api-key: YOUR_API_KEY
```

## Path Parameters

<ParamField path="identifier" type="string" required>
  Identifies the contact to retrieve metrics for. Accepted formats:

  * `id:{uuid}` — prefixed Shilo UUID (e.g. `id:ee6f2136-b94a-4438-9335-3acf5b2a0d31`)
  * `external_contact_id:{string}` — your CRM or system's contact ID (e.g. `external_contact_id:contact_xyz789`)
  * `{uuid}` — bare Shilo UUID (e.g. `ee6f2136-b94a-4438-9335-3acf5b2a0d31`)
</ParamField>

## Query Parameters

<ParamField query="date_gte" type="string">
  Inclusive lower date bound as an ISO date or date-time. Date-only values use UTC start of day. Defaults to UTC start of day 29 days ago. Example: `2026-03-26T00:00:00Z`.
</ParamField>

<ParamField query="date_lte" type="string">
  Inclusive upper date bound as an ISO date or date-time. Date-only values use UTC end of day. Defaults to the request time. Example: `2026-04-24T18:30:00Z`.
</ParamField>

<ParamField query="source" type="string">
  Comma-separated list of source IDs to filter by. Example: `source-1,source-2`.
</ParamField>

<ParamField query="stage" type="string">
  Comma-separated list of pipeline stage IDs to filter by. Example: `stage-1,stage-2`.
</ParamField>

<ParamField query="team" type="string">
  Comma-separated list of team IDs to filter by. Example: `team-1,team-2`.
</ParamField>

<ParamField query="type" type="string" default="all">
  Filter by call direction. Accepted values: `all`, `inbound`, `outbound`.
</ParamField>

## Response

### 200 — Success

Returns a `Metrics` object with aggregated performance data for the specified contact. The fields mirror the calculations shown in the contact-level insights view in the Shilo web app.

### 400 — Bad Request

One or more query parameters are invalid, or the `identifier` format is not recognized.

### 401 — Unauthorized

Your API key is missing or invalid.

### 404 — Not Found

No contact matching the provided `identifier` was found in your organization.

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.shilo.ai/api/v1/contacts/external_contact_id:contact_xyz789/metrics?date_gte=2026-03-26T00:00:00Z&type=inbound" \
  --header "x-api-key: YOUR_API_KEY"
```