> ## 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 User Metrics — Shilo API Reference

> Retrieve dashboard-aligned performance metrics for a single agent. Filter by date range, source, stage, team, and call direction. Matches the web app view.

Use this endpoint to retrieve call performance metrics for a specific agent. The data mirrors what managers and agents see in the Shilo web app's insights view, and can be scoped by date range, lead source, pipeline stage, team, and call direction. This makes it easy to embed agent-level analytics in your own reporting tools, CRM dashboards, or automated performance review processes.

## Endpoint

```
GET https://api.shilo.ai/api/v1/users/{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 user. Three formats are supported:

  | Format              | Example                                   |
  | ------------------- | ----------------------------------------- |
  | Plain Shilo UUID    | `ee6f2136-b94a-4438-9335-3acf5b2a0d31`    |
  | Prefixed Shilo UUID | `id:ee6f2136-b94a-4438-9335-3acf5b2a0d31` |
  | External user ID    | `external_user_id:agent-1`                |
</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. Useful when an agent belongs to multiple teams and you want to isolate performance for a specific one.
</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 contact-level metrics endpoints, scoped to this user'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 user found matching the provided identifier.   |

## Example Request

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/users/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 user ID with a date range and call direction

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

### Filter by team

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/users/external_user_id:agent-1/metrics?team=team-101,team-202&type=all" \
  -H "x-api-key: YOUR_API_KEY"
```