---
title: "Get team credit usage over time"
method: POST
path: "/v1/analytics/team-credit-usage"
tags: ["Analytics"]
---

# Get team credit usage over time

`POST /v1/analytics/team-credit-usage`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/analytics/team-credit-usage`
- Auth: API key in header `x-magnific-api-key`

Returns credit consumption for the caller's team aggregated into time buckets.
Authenticates via API key (`X-Magnific-API-Key` header). The caller's identity
is resolved automatically from the API key.

Response always includes per-user breakdown with email and per-project grouping
(same data as the CSV export). Each row carries both the tool category as a
display name in `tool` (e.g. "AI Image Models") and the specific tool that was
billed in `tool_name`.

Reconciling usage: many tools share a category, so `tool` alone does not identify
a row. Rows with the same `tool`, user, project and date are distinct consumptions
— tell them apart by `tool_name` and sum their credits. De-duplicating them
undercounts real usage.

Date range limits: Enterprise up to 365 days, Business up to 180 days.
If no dates are provided, defaults to the last 7 days.

Available exclusively for Business and Enterprise plans. Rate limit: 100 RPD.

Response field mapping (differs from internal endpoints):
- `tool`: tool category as a display name (e.g. "AI Image Models")
- `tool_name`: the specific tool billed (e.g. "pikaso-tti-flux-dev")
- `user_uses`: number of operations (replaces `count`)
- `user_credits`: credits consumed (replaces `total_amount`/`amount`)
- `project_reference`: project UUID (replaces `folder_reference`)

## Request body

- V1AnalyticsTeamCreditUsagePostRequest
  - `granularity` 'day' | 'week' | 'month' | 'year': Time bucket granularity for aggregation. Defaults to `day` if omitted.
  - `start_date` string, date: Start date for the query range (YYYY-MM-DD). Defaults to 7 days ago.
  - `end_date` string, date: End date for the query range (YYYY-MM-DD). Defaults to today.
  - `project_references` string[]: Filter by specific project references.
  - `api_key_ids` string[]: Filter by specific API key IDs.
  - `group_ids` integer[]: Filter by specific team group IDs. Members of these groups are included in the results.

## Response `200`

OK

- V1AnalyticsTeamCreditUsagePost200Response
  - `data` TeamCreditUsageResponseInner[]
    - `date` string, date-time: Start date of the time period.
    - `consumptions` TeamCreditUsageResponseInnerConsumptionsInner[]
      - `tool` string: Tool category display name. Many tools share a category, so this value does not identify a row on its own — use `tool_name` for that.
      - `tool_name` string: Specific tool that was billed. Two rows with the same `tool`, user, project and date are distinct consumptions, not duplicates: they are told apart by this field and their credits must be summed, not de-duplicated.
      - `user_uses` integer: Number of operations in this period.
      - `user_credits` integer: Total credits consumed.
      - `user_usages` TeamCreditUsageResponseInnerConsumptionsInnerUserUsagesInner[]: Per-user breakdown. Always included. An entry is normally attributable to one of two things: a person, identified by `user_email` and `user_reference`, or an API key, identified by `api_key_id` and `api_key_name`. An entry may still carry none of them. That happens when the user behind it cannot be resolved and no reference is available for them, and it is real usage that is counted in the parent totals like any other — reconcile it against those totals rather than treating it as missing data.
        - `user_email` string, nullable: User email address. `null` when the user could not be resolved (deleted account) and on entries generated by an API key, which belong to no person. The consumption is still counted in the parent totals either way. To attribute a `null` entry, use `api_key_id` when it is present — the entry came from a key, not a person — and `user_reference` otherwise.
        - `user_reference` string, nullable: Opaque, stable identifier of the person behind this entry. It does not change over time, so entries from different periods belonging to the same person can be matched even once their account has been deleted and `user_email` has become `null`. It reveals nothing about the person and is scoped to your team: the same individual appears under a different reference in another team's reports. `null` on entries generated by an API key, which belong to no person — use `api_key_id` there — and on entries whose user has no reference available.
        - `api_key_id` string, nullable: API key that generated this consumption, when it was not made by a person. Matches `api_key_id` in `GET /v1/analytics/team-api-keys`, so the two responses can be joined. Absent on entries made by a person.
        - `api_key_name` string, nullable: Display name of `api_key_id`. `null` when the name cannot be resolved; the entry is still attributable through `api_key_id`. Keys deleted after generating the consumption keep their name.
        - `user_uses` integer: Number of operations by this user.
        - `user_credits` integer: Credits consumed by this user.
        - `project_reference` string: Project UUID, if any.
        - `project_name` string: Project name, if resolvable.
        - `group_name` string: Group name, if resolvable.

## Other responses

- `400`: Bad Request - The server could not understand the request due to invalid syntax.
- `403`: Forbidden - The client does not have permission to access the requested resource.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)