---
agentTools:
  projectIndex: https://developers.pipefy.com/llms.txt
---

# Monthly AI Credit Usage Across Organizations

Retrieve AI credit consumption month by month, split by origin and compared against the contracted limit, aggregated across a set of organizations the authenticated user can access.

### **Before You Begin**

* **GraphQL Playground**:
  🔗 All examples should be run in the [GraphQL Playground](https://app.pipefy.com/graphiql).
  ➡️ New to GraphQL? Review the [Playground Basics Guide](https://developers.pipefy.com/reference/exploring-the-playground).
* **Authentication**:
  🛠️ Use [Service Account tokens](https://developers.pipefy.com/reference/service-accounts) *(Personal Access Tokens are deprecated)*.

### **Prerequisites**

* A role that grants the **Usage Stats** permission in each organization you want to include. This is the same permission that controls access to the *Usage Statistics* page in the Pipefy app. Organizations where you do not have it are dropped from the aggregation and listed in `excludedOrganizations`. Organization admins manage this under **Roles & Permissions**.

***

### **Step 1. List the organizations you can query**

The query expects an explicit list of organization UUIDs. The easiest way to obtain that list is the [`myUsageStatsOrganizations`](./my-usage-stats-organizations-query) query, which returns every organization where the authenticated user has the *Usage Stats* permission:

```graphql
{
  myUsageStatsOrganizations {
    uuid
    name
  }
}
```

Pick the `uuid` values you want to aggregate and pass them to `aiCreditUsageMonthly` (1 to 25 UUIDs per call).

### **Step 2. Query the monthly series**

```graphql
query aiCreditUsageMonthly(
  $organizationUuids: [ID!]!
  $range: AiCreditMonthlyRange
) {
  aiCreditUsageMonthly(organizationUuids: $organizationUuids, range: $range) {
    data {
      date
      automations
      behaviors
      assistants
      total
      limit
      overUsed
    }
    excludedOrganizations {
      uuid
    }
  }
}
```

**Input Explanation**:

* **organizationUuids**: List of organization UUIDs to aggregate. Must contain between 1 and 25 entries. Unauthorized or unknown UUIDs are dropped from the aggregation and returned in `excludedOrganizations`.
* **range**: Trailing window of the series. Accepts `last_6_months` or `last_12_months`, and defaults to `last_12_months` when omitted. There is no period argument: the window is a property of this field, not a user-selected filter.

**Sample response**:

```json
{
  "data": {
    "aiCreditUsageMonthly": {
      "data": [
        { "date": "2025-09-01", "automations": 1200.5, "behaviors": 300.0, "assistants": 0.0, "total": 1500.5, "limit": 30000.0, "overUsed": 0.0 },
        { "date": "2026-03-01", "automations": 30000.0, "behaviors": 2400.0, "assistants": 0.0, "total": 32400.0, "limit": 30000.0, "overUsed": 2400.0 },
        { "date": "2026-08-01", "automations": 980.25, "behaviors": 145.75, "assistants": 500.0, "total": 1626.0, "limit": 0.0, "overUsed": 0.0 }
      ],
      "excludedOrganizations": []
    }
  }
}
```

*(Abbreviated: a `last_12_months` response carries all 12 items, including months with no consumption, where every credit field is `0.0`.)*

**Response Breakdown**:

> **Key Fields**:
>
> * `data`: One item per month in the selected range, ascending by `date`. A `last_12_months` call always returns 12 items and a `last_6_months` call always returns 6.
> * `date`: First day of the bucket month, in UTC. Use it directly as the chart label.
> * `automations` / `behaviors` / `assistants`: Credits consumed by each origin in that month, summed across the organizations that were aggregated.
> * `total`: Sum of the three origins, computed server side. Do not re-derive it on the client.
> * `limit`: The contracted AI credit add-on for that month, summed across the organizations that were aggregated. `0.0` means no aggregated organization had an add-on that month.
> * `overUsed`: The part of `total` above `limit` for that month, computed server side. Always `0.0` when `limit` is `0.0`.
> * `excludedOrganizations`: The requested UUIDs that were dropped, each carrying only its `uuid`. Empty when the series covers every organization you asked for.

***

## **Key Notes**

* **Every month is present, and gaps are zeros rather than nulls.** A month with no consumption is returned with all four values at `0.0`, so a chart never has to synthesize missing points. No credit field is ever `null`.
* **The last item is the current month, and it is partial by definition.** It counts from the first day of the month up to now. For an organization that started its current subscription mid-month, this value can read higher than the "this month" figure on the AI tab, which counts from the subscription date instead of the first of the month.
* **Credits are floats and are never rounded.** Round for display only.
* **Assistants credits follow a per-organization flag.** An organization without the assistants usage stats flag contributes `0` to `assistants` while its `automations` and `behaviors` are unaffected. So a non-zero `assistants` value reflects only the organizations where the feature is active.
* **`limit` is the contracted add-on, and nothing else.** It is not a billing figure, it is not the threshold at which AI stops working for an organization, and it does not include the free credits a new organization receives. Do not use it to reconcile an invoice or to predict when AI will be blocked.
* **`limit: 0.0` means "no contracted add-on that month", so there is nothing to compare against.** It is what a month before the add-on was contracted returns, and also what a month missing from the source returns: the two are indistinguishable in the underlying data, which is why there is no per-month "known" flag. When rendering a reference line, draw it only where `limit` is greater than `0`; a line pinned at zero would make every bar read as over the limit.
* **`overUsed` is `0.0` whenever `limit` is `0.0`**, whatever the consumption in that month. Without that rule a month with no add-on would report its entire consumption as excess.
* **`overUsed` compares the two aggregates, not each organization against its own limit.** An organization above its limit can be offset by another below it, so this figure under-reports what billing would count as excess. The upside is that it is always consistent with `limit`: excess appears only when the aggregate bar is genuinely above the aggregate line. For per-organization limits in a single window, use [`aiCreditUsageStatsCombined`](./ai-credit-usage-stats-combined-query).
* **On the first day of a month, the current bucket can report `limit: 0.0`.** The add-on source is a day behind, so the current month may not have a row yet. Consumption is unaffected.
* **The series is an aggregate, not a per-organization breakdown.** To compare organizations against each other, use the `byOrganization` rows of [`aiCreditUsageStatsCombined`](./ai-credit-usage-stats-combined-query).
* **History depth follows metering retention.** Months older than the retention window of the underlying metering table come back as `0.0` rather than being omitted, so the response shape stays the same.
* **Results are cached for one minute**, keyed by the set of organizations and the range. Back-to-back identical requests return from cache.
* **Use [`myUsageStatsOrganizations`](./my-usage-stats-organizations-query) to discover the input list.** Feeding its `uuid` values into this query guarantees an empty `excludedOrganizations`.