> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.dealsignal.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dealsignal.com/_mcp/server.

# Credits Overview

> Check your credit balance and today's profile-request volume.

The Credit Metrics endpoint returns a snapshot of the authenticated user's account: identity, remaining subscription credits, and the day's Contact Profile Refresh activity. Use it to gate large jobs and to surface usage in your own dashboards. It is read-only and consumes no credits.

---

## Quickstart

```bash
curl -H "Accept: application/json" \
  "https://app.dealsignal.com/api/v1/users/credit_metrics?api_key=YOUR_API_KEY"
```

```json
{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "username": "jane.smith",
  "current_subscription_data": {
    "remaining_credits": 6750
  },
  "daily_profile_request_metrics": {
    "requested": 42,
    "requested_with_ds_contact_id": 30,
    "requested_without_ds_contact_id": 12
  }
}
```

The metrics object is the JSON body itself — there is no envelope.

---

## Response fields

| Field                                                           | Description                                                                                                                                                                    |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `email`                                                         | Account email.                                                                                                                                                                 |
| `name`                                                          | Display name.                                                                                                                                                                  |
| `username`                                                      | Account username.                                                                                                                                                              |
| `current_subscription_data.remaining_credits`                   | Contact / Company credits still available — the plan's allowance plus additional credits and adjustments, minus consumption. Never negative.                                   |
| `daily_profile_request_metrics.requested`                       | Contact Profile Refresh **profiles** submitted today. Profiles of a synchronous request that were matched and already `completed` in the create response are usually left out. |
| `daily_profile_request_metrics.requested_with_ds_contact_id`    | Subset submitted **with** a `ds_contact_id` (refresh path).                                                                                                                    |
| `daily_profile_request_metrics.requested_without_ds_contact_id` | Subset submitted **without** a `ds_contact_id` (search-and-refresh path), whether or not a contact was matched later.                                                          |

> **Info**
>
> `daily_profile_request_metrics` counts **profile rows, not requests** — a single request with 40 profiles adds 40. The window is the current **server** date, so the counts start again at the next server-day boundary (not midnight in your timezone). Profiles of a synchronous request that were matched and already `completed` in the create response are usually not counted; every other profile is, including profiles closed at creation without a match (`contact_data.id` `null`) and every profile of an asynchronous request. Requests submitted with `test: true` are excluded. `requested` always equals the sum of the two subsets.

> **Note**
>
> Send `Accept: application/json` from API clients so that authentication errors come back as JSON. An invalid `api_key` returns `401` with `{ "message": "Invalid api key" }`.

---

## Recommended patterns

* **Pre-flight check.** Read `current_subscription_data.remaining_credits` before submitting a large LE job or a big refresh request and refuse to launch below a configured threshold. A refresh request is rejected with `422` when your balance is too low, but passing that check doesn't guarantee the final charge is covered — size your threshold on the maximum credits per profile for the attributes you request (see [Pricing](/documentation/contact-profile-refresh-requests/overview#pricing)).
* **Dashboards.** Poll once per minute (or longer) and cache — the snapshot only changes when jobs consume credits or refresh profiles are submitted.
* **Mix monitoring.** Alert when the `requested_without_ds_contact_id` share exceeds your normal mix — search-and-refresh profiles are noisier than refreshes by `ds_contact_id`.

---

## Endpoint reference

| Endpoint                                                                    | Method | Purpose                     |
| --------------------------------------------------------------------------- | ------ | --------------------------- |
| [`/api/v1/users/credit_metrics`](/api-reference/credits/get-credit-metrics) | `GET`  | Get current credit metrics. |