Combined AI Credit Usage Stats

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 will be silently dropped from the response (see partial below). Organization admins manage this under Roles & Permissions.

Step 1. List the organizations you can query

The combined 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 combine and pass them to aiCreditUsageStatsCombined (1 to 25 UUIDs per call).

Step 2. Query combined AI credit usage

Run the following query with the list of organization UUIDs and the desired time period:

query aiCreditUsageStatsCombined(
  $organizationUuids: [ID!]!
  $period: PeriodFilter!
) {
  aiCreditUsageStatsCombined(organizationUuids: $organizationUuids, period: $period) {
    total {
      usage
      limit
      aiAutomationUsage
      assistantsUsage
    }
    byOrganization {
      organizationUuid
      organizationName
      usage
      limit
      hasAddon
      aiAutomation {
        usage
        enabled
      }
      assistants {
        usage
        enabled
      }
    }
    topAgents {
      agentId
      agentName
      organizationUuid
      organizationName
      creditsProcessed
    }
    filterDate {
      from
      to
    }
    partial
  }
}

Input Explanation:

• organizationUuids: List of organization UUIDs to aggregate. Must contain between 1 and 25 entries. Unauthorized or unknown UUIDs are silently dropped from byOrganization and flip partial to true.
• period: Time window for the stats. Use current_month, last_month, or last_3_months.

Sample response:

{
  "data": {
    "aiCreditUsageStatsCombined": {
      "total": {
        "usage": 245.5,
        "limit": 1000,
        "aiAutomationUsage": 220.0,
        "assistantsUsage": 25.5
      },
      "byOrganization": [
        {
          "organizationUuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
          "organizationName": "Acme Corp",
          "usage": 180.0,
          "limit": 500,
          "hasAddon": true,
          "aiAutomation": { "usage": 165.0, "enabled": true },
          "assistants": { "usage": 15.0, "enabled": false }
        },
        {
          "organizationUuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
          "organizationName": "Globex",
          "usage": 65.5,
          "limit": null,
          "hasAddon": false,
          "aiAutomation": { "usage": 55.0, "enabled": true },
          "assistants": { "usage": 10.5, "enabled": false }
        }
      ],
      "topAgents": [
        {
          "agentId": "c3f9a1b2-3333-4e5f-a6b7-111222333444",
          "agentName": "Invoice Processor",
          "organizationUuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
          "organizationName": "Acme Corp",
          "creditsProcessed": 95.0
        },
        {
          "agentId": "d4e0b2c3-4444-5f6a-b7c8-222333444555",
          "agentName": "Onboarding Assistant",
          "organizationUuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
          "organizationName": "Globex",
          "creditsProcessed": 55.0
        }
      ],
      "filterDate": {
        "from": "2026-05-01T00:00:00Z",
        "to": "2026-05-27T00:00:00Z"
      },
      "partial": false
    }
  }
}

Response Breakdown:

Key Fields:

• total.usage: Sum of AI credit usage across the organizations returned in byOrganization.
• total.limit: Sum of per-organization AI credit limits. null when no organization in the response has a contracted limit; organizations with a null per-org limit are treated as 0 in the sum.
• total.aiAutomationUsage: Sum of AI automation (agents + automations) credits across all returned organizations.
• total.assistantsUsage: Sum of AI assistants credits across all returned organizations.
• byOrganization: One row per organization that responded successfully. Each row includes a hasAddon flag indicating whether the organization has a paid AI credit add-on, and aiAutomation / assistants slices breaking down usage by resource type.
• topAgents: Up to 10 AI automation agents (excludes AI assistants) ranked by creditsProcessed descending across all returned organizations. agentName is null when the underlying automation record has been deleted.
• partial: true when at least one input UUID is missing from byOrganization. This happens for two reasons: (1) the caller does not have the Usage Stats permission in that organization, or (2) the per-org fetch failed transiently. Re-run the query if you suspect a transient failure.
• filterDate: Resolved from/to boundaries of the requested period, useful for labeling charts.

Key Notes

• Per-org caching. Unlike the single-org AI credit screen (which is uncached), the combined query caches each organization's result for 1 minute. This means back-to-back requests for the same organization and period return instantly from cache, even across different multi-org combinations. Changing period or organizationUuids bypasses the relevant cache entries.
• total.limit null handling. If no organization in the response has a contracted AI credit limit, total.limit is null. If at least one does, the sum is returned and orgs without a limit count as 0 toward it.
• hasAddon is per-org only. The total does not aggregate hasAddon — it is only meaningful at the organization level. Use the byOrganization rows to identify which organizations have a paid add-on.
• topAgents excludes AI assistants. Only AI automation agents (behaviors) appear in the leaderboard. Assistants usage is reflected in total.assistantsUsage and the assistants slice on each byOrganization row, but not in topAgents.
• Use myUsageStatsOrganizations to discover the input list. It returns exactly the organizations the authenticated user is eligible to query, so feeding its uuid values into aiCreditUsageStatsCombined guarantees partial: false for the authorization-drop case.