> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnific.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API

> Track your team AI credit consumption and discover team resources with the Magnific Analytics API.

<Card title="Team analytics" icon="chart-line">
  Programmatic access to the same credit usage data available in your dashboard and CSV export.
</Card>

The Analytics API lets you retrieve your team's AI credit consumption data programmatically. Integrate usage data directly into your reporting pipelines, BI tools, or internal dashboards.

Available exclusively for **Business** and **Enterprise** plans at no additional cost. It does not consume credits.

## Credit usage

Query credit consumption over time with [`POST /v1/analytics/team-credit-usage`](/api-reference/analytics/team-credit-usage/query). Each response includes per-user breakdown with email addresses and per-project grouping automatically.

```bash theme={null}
curl -X POST https://api.magnific.com/v1/analytics/team-credit-usage \
  -H "X-Magnific-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "granularity": "day",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31",
    "group_ids": [10]
  }'
```

### Example response

```json theme={null}
{
  "data": [
    {
      "date": "2026-05-01T00:00:00+00:00",
      "consumptions": [
        {
          "tool": "AI Image Models",
          "user_uses": 45,
          "user_credits": 1800,
          "user_usages": [
            {
              "user_email": "designer@company.com",
              "user_uses": 30,
              "user_credits": 1200,
              "project_reference": "a1b2c3d4-1111-4000-8000-000000000001",
              "project_name": "Marketing Campaign",
              "group_name": "Design Team"
            },
            {
              "user_email": "developer@company.com",
              "user_uses": 15,
              "user_credits": 600
            }
          ]
        },
        {
          "tool": "Asset Download",
          "user_uses": 10,
          "user_credits": 900
        }
      ]
    }
  ]
}
```

### Filtering

Narrow down results to specific subsets of your team:

| Filter               | What it does                                          | Where to get the IDs                                                        |
| -------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
| `group_ids`          | Show only consumption from members of specific groups | [`GET /v1/analytics/team-groups`](/api-reference/analytics/team-groups)     |
| `project_references` | Show only consumption within specific projects        | [`GET /v1/analytics/team-projects`](/api-reference/analytics/team-projects) |
| `api_key_ids`        | Show only consumption from specific API keys          | [`GET /v1/analytics/team-api-keys`](/api-reference/analytics/team-api-keys) |

### Time granularity

The `granularity` parameter controls the time bucket size. Defaults to `day`.

| Value   | Description                                 | Best for                      |
| ------- | ------------------------------------------- | ----------------------------- |
| `day`   | One data point per calendar day             | Short ranges (up to 30 days)  |
| `week`  | One data point per ISO week (Monday–Sunday) | Medium ranges (1–3 months)    |
| `month` | One data point per calendar month           | Quarterly or yearly overviews |
| `year`  | One data point per calendar year            | Multi-year trend analysis     |

### Date range limits

* If no dates are provided, returns the **last 7 days**
* **Enterprise**: maximum 365 days
* **Business**: maximum 180 days

## Discovery endpoints

Four companion endpoints let you list team resources and get the IDs needed for filtering credit usage:

| Endpoint                                                                    | Returns                              |
| --------------------------------------------------------------------------- | ------------------------------------ |
| [`GET /v1/analytics/team-members`](/api-reference/analytics/team-members)   | Members with email, role, and status |
| [`GET /v1/analytics/team-api-keys`](/api-reference/analytics/team-api-keys) | API keys with name and status        |
| [`GET /v1/analytics/team-groups`](/api-reference/analytics/team-groups)     | Groups with name and member count    |
| [`GET /v1/analytics/team-projects`](/api-reference/analytics/team-projects) | Projects with name                   |

Cache discovery results — team composition changes infrequently.

## Authentication

All endpoints authenticate with the `X-Magnific-API-Key` header. Your team is identified automatically from the API key. See [Authentication](/authentication) for details.

## Rate limits

All Analytics API endpoints are limited to **100 requests per day** (100 RPD).

## API reference

<div className="my-11">
  <Columns cols={2}>
    <Card title="Credit Usage" icon="chart-line" href="/api-reference/analytics/team-credit-usage/query">
      Query credit consumption over time with filters
    </Card>

    <Card title="Team Members" icon="users" href="/api-reference/analytics/team-members">
      List members with email, role, and status
    </Card>

    <Card title="API Keys" icon="key" href="/api-reference/analytics/team-api-keys">
      List API keys with name and status
    </Card>

    <Card title="Team Groups" icon="user-group" href="/api-reference/analytics/team-groups">
      List groups with member count
    </Card>

    <Card title="Team Projects" icon="folder" href="/api-reference/analytics/team-projects">
      List projects with name
    </Card>
  </Columns>
</div>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What data does the Analytics API provide?">
    The same data available in your Credit Usage dashboard and CSV export: date, tool (display name), user email, usage count, credits consumed, project, and group. The difference is structured JSON instead of flat CSV rows.
  </Accordion>

  <Accordion title="Does using the Analytics API cost credits?">
    No. The Analytics API is included with your Business or Enterprise plan at no additional cost.
  </Accordion>

  <Accordion title="How do I know which IDs to use for filtering?">
    Call the discovery endpoints first. For example, `GET /v1/analytics/team-groups` returns all your groups with their `group_id`. Pass those IDs into the `group_ids` filter when querying credit usage. The same applies to projects (`project_references`) and API keys (`api_key_ids`).
  </Accordion>

  <Accordion title="What is the maximum date range?">
    Enterprise plans can query up to 365 days. Business plans can query up to 180 days. If no dates are provided, the API defaults to the last 7 days.
  </Accordion>
</AccordionGroup>