Monthly AI Credit Usage Across Organizations

Before You Begin

GraphQL Playground:
🔗 All examples should be run in the GraphQL Playground.
➡️ New to GraphQL? Review the Playground Basics Guide.
Authentication:
🛠️ Use Service Account tokens (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 query, which returns every organization where the authenticated user has the Usage Stats permission:

{
  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

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:

{
  "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.
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.
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 to discover the input list. Feeding its uuid values into this query guarantees an empty excludedOrganizations.