API Reference

Combined Automation Usage Stats

Retrieve combined automation usage with per-organization, per-pipe, and top-automation breakdowns across organizations the authenticated user can access.

Before You Begin

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 automationsUsageDetailsCombined (1 to 25 UUIDs per call).

Step 2. Query combined automation usage

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

query automationsUsageDetailsCombined(
  $organizationUuids: [ID!]!
  $period: PeriodFilter!
) {
  automationsUsageDetailsCombined(organizationUuids: $organizationUuids, period: $period) {
    total {
      usage
    }
    byOrganization {
      organizationUuid
      organizationName
      usage
      lastUpdatedAt
    }
    byPipe {
      pipe {
        uuid
        name
        icon
        color
      }
      organizationUuid
      organizationName
      usage
      lastUpdatedAt
    }
    topAutomations {
      id
      name
      usage
      action
      event
      status
      actionRepo {
        color
        icon
        name
        uuid
      }
      eventRepo {
        color
        icon
        name
        uuid
      }
      createdAt
      createdBy {
        id
        name
      }
      updatedAt
      organizationUuid
      organizationName
    }
    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.
  • Field selection: Request only the breakdown fields you need. Omit byOrganization or byPipe from the query when you do not need that view — the server skips building unused breakdowns.

Sample response:

{
  "data": {
    "automationsUsageDetailsCombined": {
      "total": {
        "usage": 847
      },
      "byOrganization": [
        {
          "organizationUuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
          "organizationName": "Acme Corp",
          "usage": 612,
          "lastUpdatedAt": "2026-05-28T14:22:10Z"
        },
        {
          "organizationUuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
          "organizationName": "Globex",
          "usage": 235,
          "lastUpdatedAt": "2026-05-27T09:15:44Z"
        }
      ],
      "byPipe": [
        {
          "pipe": {
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "HR Requests",
            "icon": "pipefy",
            "color": "blue"
          },
          "organizationUuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
          "organizationName": "Acme Corp",
          "usage": 412,
          "lastUpdatedAt": "2026-05-28T14:22:10Z"
        },
        {
          "pipe": {
            "uuid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "name": "Onboarding",
            "icon": "users",
            "color": "purple"
          },
          "organizationUuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
          "organizationName": "Acme Corp",
          "usage": 200,
          "lastUpdatedAt": "2026-05-26T11:05:30Z"
        },
        {
          "pipe": {
            "uuid": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "name": "Operations",
            "icon": "pipefy",
            "color": "green"
          },
          "organizationUuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
          "organizationName": "Globex",
          "usage": 235,
          "lastUpdatedAt": "2026-05-27T09:15:44Z"
        }
      ],
      "topAutomations": [
        {
          "id": "42",
          "name": "Move card on approval",
          "usage": 312.0,
          "action": "move_card",
          "event": "card_moved",
          "status": "active",
          "actionRepo": {
            "color": "blue",
            "icon": "pipefy",
            "name": "HR Requests",
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "eventRepo": {
            "color": "blue",
            "icon": "pipefy",
            "name": "HR Requests",
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "createdAt": "2025-11-03T10:00:00Z",
          "createdBy": {
            "id": "1001",
            "name": "Jane Admin"
          },
          "updatedAt": "2026-05-28T14:22:10Z",
          "organizationUuid": "8a1c4f10-1111-4d2c-9c2a-abc123def456",
          "organizationName": "Acme Corp"
        },
        {
          "id": "87",
          "name": "Scheduled cleanup",
          "usage": 198.0,
          "action": "create_card",
          "event": "scheduler",
          "status": "active",
          "actionRepo": {
            "color": "green",
            "icon": "pipefy",
            "name": "Operations",
            "uuid": "c3d4e5f6-a7b8-9012-cdef-345678901234"
          },
          "eventRepo": {
            "color": "green",
            "icon": "pipefy",
            "name": "Operations",
            "uuid": "c3d4e5f6-a7b8-9012-cdef-345678901234"
          },
          "createdAt": "2026-01-15T08:30:00Z",
          "createdBy": {
            "id": "1002",
            "name": "Ops Bot"
          },
          "updatedAt": "2026-05-27T09:15:44Z",
          "organizationUuid": "b27d5e21-2222-4a3b-8d1b-def456abc789",
          "organizationName": "Globex"
        }
      ],
      "filterDate": {
        "from": "2026-05-01T00:00:00Z",
        "to": "2026-05-27T00:00:00Z"
      },
      "partial": false
    }
  }
}

Response Breakdown:

Key Fields:

  • total.usage: Sum of automation usage across all authorized organizations in the response.
  • byOrganization: One row per authorized organization, ordered by usage descending. Organizations with no automation usage in the period appear with usage: 0.
  • byPipe: Top pipes (automation event repos) by usage in the period, ordered by usage descending (ties broken by pipe name, then organization name). Defaults to the top 10; pass byPipeLimit: null on the query to return all pipes with usage. Pipes with zero usage are omitted. Each row includes organizationUuid and organizationName because the same pipe name can exist in different organizations.
  • lastUpdatedAt: When automations in that organization or on that pipe were last updated among those counted in the period. null when the organization has zero usage (byOrganization only).
  • topAutomations: Up to 10 automations with the highest usage across the returned organizations. Each row includes the automation details and the organization it belongs to.
  • partial: true when at least one organization you requested is missing from byOrganization — for example, you lack Usage Stats permission in that org. Zero usage alone does not set partial to true.
  • filterDate: The start and end dates that correspond to the period you requested, useful for labeling charts.

Key Notes

  • Request only the breakdown you need. Include byOrganization for org-level charts, byPipe for pipe-level views, or both. Omitting a field from the GraphQL selection skips that aggregation on the server.
  • Use period to choose the time window. Pass current_month, last_month, or last_3_months as the query input. Request filterDate in the response when you need the exact date range for display.
  • Use myUsageStatsOrganizations to discover the input list. It returns the organizations the authenticated user is eligible to query.
  • byPipe groups by event repo, not action repo. The pipe shown is where the automation trigger event occurs (for example, the pipe a card was moved in), matching single-org automation usage stats.
  • byPipeLimit controls how many pipes are returned. Omitted or default is 10 (top by usage). Pass byPipeLimit: null when you need every pipe with usage in the period.
  • Deleted automations may still appear in topAutomations with status: deleted if they ran during the period.
  • Scheduler automations are included in totals and topAutomations like any other automation.

Updated 2 days ago

Updated 2 days ago