# Querying Customer Usage

The [query-customer-usage](https://github.com/prismatic-io/examples/tree/main/scripts/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](https://prismatic.io/docs/integrations/usage-limits.md).

## Run the script[​](#run-the-script "Direct link to Run the script")

You need [Node.js](https://nodejs.org/) 22 or later and the [Prism CLI tool](https://prismatic.io/docs/cli.md), 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

```bash
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](https://prismatic.io/docs/api/authentication.md) 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](https://prismatic.io/docs/configure-prismatic/deployment-regions.md), 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[​](#report-deployed-instances-per-customer "Direct link to Report deployed instances per customer")

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

### List customers[​](#list-customers "Direct link to List customers")

The script pages through the [customers](https://prismatic.io/docs/api/schema/queries.md#customers) query, sorted by name:

List customers

```graphql
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](https://prismatic.io/docs/api/pagination.md).

### Get usage snapshots for each customer[​](#get-usage-snapshots-for-each-customer "Direct link to Get usage snapshots for each customer")

For each customer, the script pages through the [customerTotalUsageMetrics](https://prismatic.io/docs/api/schema/queries.md#customertotalusagemetrics) query:

Get a customer's usage snapshots

```graphql
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

```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[​](#report-compute-usage-per-instance "Direct link to Report compute usage per instance")

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

### List instances[​](#list-instances "Direct link to List instances")

The script pages through the [instances](https://prismatic.io/docs/api/schema/queries.md#instances) query, sorted by customer and then by creation time:

List instances

```graphql
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[​](#get-daily-usage-for-each-instance "Direct link to Get daily usage for each instance")

For each instance, the script pages through the [instanceDailyUsageMetrics](https://prismatic.io/docs/api/schema/queries.md#instancedailyusagemetrics) query:

Get an instance's daily compute usage

```graphql
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

```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`.