API 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

Organization access: You must have a Super Admin or Admin role on the organization.
Organization UUID: You will need the organization’s UUID to run the query.

Step 1. Find the Organization UUID

You need the organization’s UUID to query API usage. Run the query below, replacing <ORGANIZATION_ID> with your organization ID:

{
  organization(id: "<ORGANIZATION_ID>") {
    uuid
  }
}

You can find the organization ID in the URL when viewing the organization in Pipefy: https://app.pipefy.com/organizations/<ORGANIZATION_ID>.

Step 2. Query API usage grouped by dimension

Run the following query with your organization UUID, the desired time period, and the dimension to group by:

  query apiUsageStats($organizationUuid: ID!, $period: PeriodFilter!, $dimension: GroupedAPIDimension) {
    apiUsageStats(organizationUuid: $organizationUuid, period: $period, dimension: $dimension) {
      data {
        dimension
        metric
        __typename
      }
      __typename
    }
  }

Input Explanation:

period: Time window for the stats. Use current_month, last_month, or last_3_months.
dimension: How to group the usage data:
- operation_name: Groups by the GraphQL operation name you set in your query (see Operation names). Queries without an operation name appear as "Not specified".
- token: Groups by the token used for the request (e.g. user/token name or service account name).
- when not passed or null: Return the total count in that period

Sample response (grouped by operation name):

{
  "data": {
    "apiUsageStatsGroupedBy": {
      "data": [
        {
          "dimension": "Not specified",
          "metric": 130,
          "__typename": "MetricItem"
        },
        {
          "dimension": "GetUsage",
          "metric": 52,
          "__typename": "MetricItem"
        },
        {
          "dimension": "GetCards",
          "metric": 36,
          "__typename": "MetricItem"
        },
        {
          "dimension": "CreateCards",
          "metric": 35,
          "__typename": "MetricItem"
        },
        {
          "dimension": "UpdatePipe",
          "metric": 34,
          "__typename": "MetricItem"
        }
      ],
      "__typename": "APIUsageSummary"
    }
  }
}

Sample response (grouped by token):

{
  "data": {
    "apiUsageStatsGroupedBy": {
      "data": [
        {
          "dimension": "John - Python Integration",
          "metric": 167,
          "__typename": "MetricItem"
        },
        {
          "dimension": "HR Integration Bot",
          "metric": 120,
          "__typename": "MetricItem"
        },
      ],
      "__typename": "APIUsageSummary"
    }
  }
}

Sample response (grouped only by period, with no dimension):

{
  "data": {
    "apiUsageStatsGroupedBy": {
      "data": [
        {
          "metric": 717,
          "dimension": "Counter",
          "__typename": "MetricItem"
        }
      ],
      "__typename": "APIUsageSummary"
    }
  }
}

The response returns an array of data entries, each with a dimension value and a metric (API call count). Results are limited to the top 10 entries for the chosen dimension.