Use Case Template

Title: List Organizations with Usage Stats Access

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 in at least one organization that grants the Usage Stats permission. This is the same permission that controls access to the Usage Statistics page in the Pipefy app — if you can open that page for an organization, the org will appear in the response; if you cannot, it will not. Organization admins manage this under Roles & Permissions.

Step 1. Execute the query

Use this query to discover which organizations the authenticated user can request usage statistics for. The returned uuid values are the inputs for the other usage-stats queries (apiUsageStats, apiUsageStatsDaily, aiCreditUsageStats, agentsUsageDetails).

{
  myUsageStatsOrganizations {
    uuid
    name
  }
}

Input Explanation:

This query takes no arguments. Eligibility is derived from the authenticated user's role in each organization.

Sample Response:

{
  "data": {
    "myUsageStatsOrganizations": [
      {
        "uuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
        "name": "Acme Corp"
      },
      {
        "uuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
        "name": "Globex"
      }
    ]
  }
}

Response Breakdown:

Key Fields:

• uuid: Use this value as the organizationUuid argument when calling any other usage-stats query.
• name: The organization's display name, useful for rendering pickers or labels in clients.

Key Notes

• Sort order. Results are sorted alphabetically by organization name (case-insensitive). Clients that render the list directly can rely on this order without re-sorting.
• Empty response. An empty list ([]) is a valid response and means the authenticated user has no organizations with usage-stats access. It is not an error condition — check the user's role in the expected organization if this is unexpected.
• No pagination. This query returns a flat list, not a Relay-style connection. There are no first/after arguments and no page size limit — the response always contains every organization the user is eligible for.
• Permission gate. Visibility is controlled by the role's Usage Stats permission. Changing a user's role (or toggling the permission on the role) changes which organizations appear here on the next request.