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
      status
      event
      type
      eventRepo {
        uuid
        name
        icon
        color
      }
      tags {
        name
      }
    }
    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,
          "status": "active",
          "event": "card_moved",
          "type": "agent_behavior",
          "eventRepo": {
            "uuid": "e5a1c3d4-5555-4b7c-9d8e-333444555666",
            "name": "Accounts Payable",
            "icon": "pipefy",
            "color": "blue"
          },
          "tags": [{ "name": "finance" }]
        },
        {
          "agentId": "d4e0b2c3-4444-5f6a-b7c8-222333444555",
          "agentName": "Onboarding Assistant",
          "organizationUuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
          "organizationName": "Globex",
          "creditsProcessed": 55.0,
          "status": "inactive",
          "event": "card_created",
          "type": "ai_automation",
          "eventRepo": null,
          "tags": null
        }
      ],
      "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.

topAgents[].status and topAgents[].event: Status of the automation behind the entry and the event that triggers it. Both are null when the automation record cannot be resolved.

topAgents[].type: Whether the credits were consumed by an agent behavior (agent_behavior) or by an AI action inside a regular automation (ai_automation). null when the automation record cannot be resolved.

topAgents[].eventRepo and topAgents[].tags: The pipe the automation is triggered from, and the tags on that pipe. Both are null when the automation has no event repo; tags is an empty list when the pipe exists but carries no tags.

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.

agents is the paginated, searchable version of topAgents. topAgents is deprecated and capped at 10 entries; agents ranks the same leaderboard, paginated with first/after (max page size 50), and additionally accepts a search argument to filter by a case-insensitive substring of agentName:

{
  aiCreditUsageStatsCombined(organizationUuids: $organizationUuids, period: $period) {
    agents(search: "invoice", first: 10) {
      totalCount
      totalCredits
      edges {
        node {
          agentId
          agentName
          organizationUuid
          creditsProcessed
          status
          event
          type
          eventRepo {
            uuid
            name
            icon
            color
          }
          tags {
            name
          }
        }
      }
    }
  }
}

Pass sort: { by: CREDITS_PROCESSED, order: ASC } to reverse the default descending order. search and sort compose: the result is filtered first, then ordered.

type tells the two credit sources apart. An entry is agent_behavior when the automation runs an AI agent behavior, and ai_automation when it runs any other AI action, such as generate_with_ai. The leaderboard ranks both together, so read type when you need to split the two in a report. The same metadata fields (status, event, eventRepo, tags) are available on the agents connection.
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.