Querying Customer Usage

The query-customer-usage example script wraps Prismatic's GraphQL API to report usage for each of your customers over a date range. It writes two CSV files:

Deployed instances: The average number of instances and unique integrations each customer had deployed on each day, which helps if you bill customers per instance.
Instance compute: Each instance's daily execution counts, step count, and compute usage in megabyte-seconds, which helps if you bill customers for compute or want to find compute-intensive instances.

This guide walks through the queries the script runs, so you can adapt them to your own billing or reporting process. For how Prismatic measures compute usage, see usage limits.

Run the script

You need Node.js 22 or later and the Prism CLI tool, logged in to your tenant. Clone the examples repository, install dependencies, and run the start script with a start date and end date in YYYY-MM-DD format:

Query customer usage for a date range
git clone https://github.com/prismatic-io/examples.git
cd examples/scripts/query-customer-usage
npm install
npm run start -- --start-date 2026-10-01 --end-date 2026-10-31

The -- passes the date options through npm to the script. The start script gets an API token by running prism me:token, and sends each request with that token as a bearer token. It retries failed requests up to five times.

Requests go to https://app.prismatic.io/api by default. To use a tenant in another region, set PRISMATIC_URL to the region's URL from deployment regions, such as https://app.eu-west-1.prismatic.io. Prism uses the same variable, so the token and the requests both target that region.

The script treats dates as UTC days, and includes both the start date and the end date.

Report deployed instances per customer

The script first lists your customers, then requests usage snapshots for each customer.

List customers

The script pages through the customers query, sorted by name:

List customers
query ($startCursor: String) {
  customers(
    after: $startCursor
    isSystem: false
    orderBy: { field: NAME, direction: ASC }
  ) {
    nodes {
      id
      externalId
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

isSystem: false excludes system-generated customers, so the report includes only customers you created. The script passes each response's pageInfo.endCursor as the next startCursor until hasNextPage is false. For more about this pattern, see pagination.

Get usage snapshots for each customer

For each customer, the script pages through the customerTotalUsageMetrics query:

Get a customer's usage snapshots
query (
  $customerId: ID!
  $snapshotStart: DateTime
  $snapshotEnd: DateTime
  $startCursor: String
) {
  customerTotalUsageMetrics(
    customer: $customerId
    sortBy: { direction: ASC, field: SNAPSHOT_TIME }
    snapshotTime_Gte: $snapshotStart
    snapshotTime_Lte: $snapshotEnd
    after: $startCursor
  ) {
    nodes {
      snapshotTime
      deployedInstanceCount
      deployedUniqueIntegrationCount
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Prismatic records a snapshot of each customer's deployed instance count about once an hour. Each snapshot includes:

Field	Description
`snapshotTime`	When Prismatic recorded the snapshot
`deployedInstanceCount`	The number of the customer's instances that were deployed
`deployedUniqueIntegrationCount`	The number of distinct integrations among the customer's deployed instances

snapshotTime_Gte and snapshotTime_Lte take DateTime values. To include every snapshot from the end date, the script sets snapshotEnd to the last millisecond of that day, such as 2026-10-31T23:59:59.999Z.

The script groups snapshots by UTC day and averages each count, so a day's value can be a fraction when the count changed during the day. Days without snapshots are left out of the report. If you'd rather report one value per day without averaging, set onlyLatestDailySnapshots: true to return only the latest snapshot for each day.

The script writes the results to customer-instance-data.csv:

customer-instance-data.csv
Customer ID,Customer Name,Date,Deployed Instances,Unique Integrations
Q3VzdG9tZXI6MGFkZjJhNzUtZGRhMy00MDIxLWI4NmItZGY1ZDk5OWM5YjEw,Acme Corp,2026-10-01,8,8
Q3VzdG9tZXI6MGFkZjJhNzUtZGRhMy00MDIxLWI4NmItZGY1ZDk5OWM5YjEw,Acme Corp,2026-10-02,8.5,8

Report compute usage per instance

The script then lists your instances and requests daily usage metrics for each one.

List instances

The script pages through the instances query, sorted by customer and then by creation time:

List instances
query ($startCursor: String) {
  instances(
    after: $startCursor
    isSystem: false
    sortBy: [
      { field: CUSTOMER, direction: ASC }
      { field: CREATED_AT, direction: ASC }
    ]
  ) {
    nodes {
      id
      name
      customer {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

isSystem: false excludes system-generated instances, such as the test instances that the integration designer uses. The query returns instances that exist when the script runs, so the report doesn't include instances deleted during the date range.

Get daily usage for each instance

For each instance, the script pages through the instanceDailyUsageMetrics query:

Get an instance's daily compute usage
query getInstanceComputeUsage(
  $instanceId: ID!
  $snapshotStart: Date!
  $snapshotEnd: Date!
  $startCursor: String
) {
  instanceDailyUsageMetrics(
    instance: $instanceId
    snapshotDate_Gte: $snapshotStart
    snapshotDate_Lte: $snapshotEnd
    after: $startCursor
    sortBy: { direction: ASC, field: SNAPSHOT_DATE }
  ) {
    nodes {
      snapshotDate
      successfulExecutionCount
      failedExecutionCount
      stepCount
      spendMbSecs
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Unlike the customer snapshots, these metrics are already daily, and snapshotDate_Gte and snapshotDate_Lte take Date values such as 2026-10-31. Each node includes:

Field	Description
`snapshotDate`	The day the metrics cover
`successfulExecutionCount`	The number of executions that succeeded
`failedExecutionCount`	The number of executions that failed
`stepCount`	The number of steps that ran
`spendMbSecs`	Compute usage in megabyte-seconds: execution time multiplied by allocated memory

The script writes the results to instance-compute-data.csv:

instance-compute-data.csv
Customer ID,Customer Name,Instance ID,Instance Name,Date,Successful Executions,Failed Executions,Step Count,Execution Mb-Seconds
Q3VzdG9tZXI6ODk4Y2Q1OTYtNzI5MS00NmQxLWE2YWMtZTA1YTNkZTEwZDJj,Johnson Homes,SW5zdGFuY2U6ZDVjNmU4YjYtMjQxYS00NDVjLTliMmItMTM2NTVlMTczZTFj,HubSpot,2026-10-01,1440,0,5760,985819
Q3VzdG9tZXI6ODk4Y2Q1OTYtNzI5MS00NmQxLWE2YWMtZTA1YTNkZTEwZDJj,Johnson Homes,SW5zdGFuY2U6ZDVjNmU4YjYtMjQxYS00NDVjLTliMmItMTM2NTVlMTczZTFj,HubSpot,2026-10-02,1440,0,5760,946312

To find your most compute-intensive instances, sort this file by Execution Mb-Seconds.

Run the script​

Report deployed instances per customer​

List customers​

Get usage snapshots for each customer​

Report compute usage per instance​

List instances​

Get daily usage for each instance​