Analytics

Get team credit usage over time

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)
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

Request body

granularity'day' | 'week' | 'month' | 'year'

Time bucket granularity for aggregation. Defaults to day if omitted.

start_datestring date

Start date for the query range (YYYY-MM-DD). Defaults to 7 days ago.

end_datestring date

End date for the query range (YYYY-MM-DD). Defaults to today.

project_referencesstring[]

Filter by specific project references.

api_key_idsstring[]

Filter by specific API key IDs.

group_idsinteger[]

Filter by specific team group IDs. Members of these groups are included in the results.

Example request

{
  "granularity": "month",
  "start_date": "2026-01-01",
  "end_date": "2026-03-31",
  "project_references": [
    "a1b2c3d4-1111-4000-8000-000000000001"
  ],
  "api_key_ids": [
    "api-key-1",
    "api-key-2"
  ],
  "group_ids": [
    10,
    20
  ]
}

Response

OK

Example response

{
  "data": [
    {
      "date": "2026-01-01T00:00:00Z",
      "consumptions": [
        {
          "tool_name": "pikaso-tti-flux-dev",
          "user_usages": [
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            },
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            }
          ],
          "user_credits": 1800,
          "user_uses": 45,
          "tool": "AI Image Models"
        },
        {
          "tool_name": "pikaso-tti-flux-dev",
          "user_usages": [
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            },
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            }
          ],
          "user_credits": 1800,
          "user_uses": 45,
          "tool": "AI Image Models"
        }
      ]
    },
    {
      "date": "2026-01-01T00:00:00Z",
      "consumptions": [
        {
          "tool_name": "pikaso-tti-flux-dev",
          "user_usages": [
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            },
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            }
          ],
          "user_credits": 1800,
          "user_uses": 45,
          "tool": "AI Image Models"
        },
        {
          "tool_name": "pikaso-tti-flux-dev",
          "user_usages": [
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            },
            {
              "user_email": "designer@company.com",
              "user_reference": "usr_a3f81c2d9e4b7f60",
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "group_name": "Design Team",
              "user_credits": 1200,
              "project_name": "Marketing Campaign",
              "user_uses": 30,
              "api_key_id": "d98b3edd-38c6-4f03-a9bd-da6eff110782",
              "api_key_name": "prod-batch"
            }
          ],
          "user_credits": 1800,
          "user_uses": 45,
          "tool": "AI Image Models"
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.