# Retrieve Metrics

::::callout{intent="warning"}
Segment metrics are currently in private beta and only available to a limited
number of users. The response shape might change before GA. [Get in
touch](https://resend.com/help) if you're interested in testing this
feature.

Once you have access, upgrade your Resend SDK to use the methods on this
page:

:::code-group
```bash Node.js
npm install resend@6.31.1-preview-headless-dashboard.0
```
:::
::::

Contact counts for your account, optionally broken down by segment. Works
across your whole account by default, or scoped to specific segments via
`segment_id`.

:::callout{intent="info"}
Responses are cached for up to 15 minutes, so repeating the same request may
return slightly stale data within that window.
:::

All parameters are optional. With none, the response covers your whole account,
includes every metric, and returns only `totals`. There's no date range, so
counts are a point-in-time snapshot rather than a historical window.

## Query Parameters

List-type query parameters below accept a comma-separated value, the
parameter repeated (`segment_id=a&segment_id=b`), or a mix of
both.

List of metrics to include in `totals` and `data`. Omit for all. See
[Metrics](#metrics).

List of dimensions to break `data` down by. Omit for only `totals`, with no
`data`.

Possible values:

- `segment`: one row per segment, using its current contact counts.

List of segment IDs. Narrows `totals` (and `data`, when requested) to just
these segments, without double-counting contacts that belong to more than one.

:::callout{intent="info"}
When `dimensions` includes `segment`, `data` is ordered by each segment's
creation date, newest first.
:::

## Metrics

Every metric counts contacts, not emails.

| Metric          | Description                                              |
| --------------- | -------------------------------------------------------- |
| `all_contacts`  | Every contact. Sum of `subscribers` and `unsubscribers`. |
| `subscribers`   | Contacts with `unsubscribed` set to `false`.             |
| `unsubscribers` | Contacts with `unsubscribed` set to `true`.              |

:::callout{intent="info"}
`totals` counts each contact once. `data` counts a contact in every segment it
belongs to.
:::

:::code-group
```ts Node.js
import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

const { data, error } = await resend.segments.metrics({
  dimensions: ['segment'],
  metrics: ['all_contacts'],
});
```

```bash cURL
curl -X GET 'https://api.resend.com/segments/metrics?dimensions=segment&metrics=all_contacts' \
     -H 'Authorization: Bearer re_xxxxxxxxx'
```
:::

:::code-group
```json Response
{
  "object": "metrics",
  "metrics": ["all_contacts"],
  "dimensions": ["segment"],
  "totals": {
    "all_contacts": 12450
  },
  "data": [
    {
      "id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
      "name": "Registered Users",
      "all_contacts": 4300
    }
  ]
}
```
:::

## Related pages

- [Account Management](./account-management-index.md)
- [API Keys](./api-keys-2-index.md)
- [API Keys](./api-keys-index.md)
- [API Reference](./api-reference-index.md)
- [AudiencesDEPRECATED](./audiencesdeprecated-index.md)
- [Authorized Apps](./authorized-apps-index.md)
- [Automations](./automations-index.md)
- [Broadcasts](./broadcasts-index.md)
- [Build with AI](./build-with-ai-index.md)
- [Changelog](../changelog.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.