> ## 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.

# Get Contact Metrics — Shilo API Reference

> Retrieve dashboard-aligned call performance metrics for a specific contact. Filter by date range, source, stage, team, and call direction.

Use this endpoint to retrieve call performance metrics for a specific contact. The data returned mirrors what you see in the Shilo web dashboard and can be scoped by date range, lead source, pipeline stage, team, and call direction. This makes it straightforward to embed contact-level analytics in your own reporting tools or CRM views.

## 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>
  The identifier used to look up the contact. Three formats are supported:

  | Format              | Example                                   |
  | ------------------- | ----------------------------------------- |
  | Plain Shilo UUID    | `ee6f2136-b94a-4438-9335-3acf5b2a0d31`    |
  | Prefixed Shilo UUID | `id:ee6f2136-b94a-4438-9335-3acf5b2a0d31` |
  | External contact ID | `external_contact_id:4534`                |
</ParamField>

## Query Parameters

<ParamField query="date_gte" type="string">
  Inclusive lower bound of the date range as an ISO date or date-time (e.g. `2024-10-01T00:00:00Z`). Date-only values use UTC start of day. Defaults to UTC start of day 29 days ago.
</ParamField>

<ParamField query="date_lte" type="string">
  Inclusive upper bound of the date range as an ISO date or date-time. Date-only values use UTC end of day. Defaults to the request time.
</ParamField>

<ParamField query="source" type="string">
  Comma-separated list of source IDs to filter by (e.g. `src-1,src-2`). Returns metrics only for calls associated with the specified lead sources.
</ParamField>

<ParamField query="stage" type="string">
  Comma-separated list of stage IDs to filter by. Returns metrics only for calls where the contact was in one of the specified pipeline stages.
</ParamField>

<ParamField query="team" type="string">
  Comma-separated list of team IDs to filter by. Returns metrics only for calls made by agents on the specified teams.
</ParamField>

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

## Response

A successful request returns HTTP `200` with a `Metrics` object. The `Metrics` shape is the same as returned by the integration-level and user-level metrics endpoints, scoped to this contact's activity.

<Note>
  The `Metrics` object uses the same calculations shown in the Shilo web app's insights view. Field names and structure align with the dashboard data model.
</Note>

## Error Codes

| Status | Meaning                                            |
| ------ | -------------------------------------------------- |
| `400`  | Invalid query parameters or malformed identifier.  |
| `401`  | Missing or invalid API key.                        |
| `404`  | No contact found matching the provided identifier. |

## Example Request

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/contacts/ee6f2136-b94a-4438-9335-3acf5b2a0d31/metrics?type=outbound&date_gte=2024-10-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"
```

### Filter by external contact ID with a custom date range

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/contacts/external_contact_id:4534/metrics?date_gte=2024-10-01T00:00:00Z&date_lte=2024-10-31T23:59:59Z&type=all" \
  -H "x-api-key: YOUR_API_KEY"
```