---
title: "Query usage"
method: POST
path: "/v2/query/usage"
tags: ["Usage", "Public-Docs"]
---

# Query usage

`POST /v2/query/usage`

Query usage for a project

## Request body

- object
  - `data` union, required
    - object — Aggregate the number of interactions that match the provided filter.
      - `name` 'interactions', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Find the top intents that match the provided filter.
      - `name` 'top_intents', required
      - `filter` object, required
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
    - object — Aggregate the number of unique users that match the provided filter.
      - `name` 'unique_users', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Aggregate the number of tokens spent that match the provided filter.
      - `name` 'credit_usage', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Aggregate the function calls that match the provided filter.
      - `name` 'function_usage', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Aggregate the API calls that match the provided filter.
      - `name` 'api_calls', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Find the knowledge base documents that match the provided filter.
      - `name` 'kb_documents', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Aggregate the integration tool calls that match the provided filter.
      - `name` 'integrations', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Aggregate the transcripts that match the provided filter.
      - `name` 'transcripts', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number
    - object — Aggregate the agent invocations that match the provided filter.
      - `name` 'agent_usage', required
      - `filter` UsageQueryBaseListFilterV2, required — A base filter supported by all queries that return a list
        - `projectID` string, required
        - `startTime` string, date-time — A timestamp in ISO-8601 format
        - `endTime` string, date-time — A timestamp in ISO-8601 format
        - `projectEnvironmentIDOrAlias` union — One or more Voiceflow project environment IDs or aliases
          - string
          - string[]
        - `limit` integer
        - `cursor` number

## Response `200`

The query succeed and the result was returned

- object
  - `result` union, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `type` string, required
    - object
      - `intents` object[], required
        - `name` string, required — The name of the intent
        - `count` integer, required — The number of times the intent was used in the project(s) that matched the provided filter
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `diagramID` string, required
        - `nodeID` string, required
        - `model` string, required
        - `type` string, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `functionID` string, required
        - `name` string, required
        - `successCount` integer, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `apiToolID` string, required
        - `name` string, required
        - `successCount` integer, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `documentID` string, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `integrationToolName` string, required
        - `successCount` integer, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
    - object
      - `cursor` integer
      - `items` object[], required
        - `period` string, date-time, required
        - `projectID` string, required
        - `environmentID` string, required
        - `count` integer, required
        - `agentID` string, required
        - `name` string, required
        - `successCount` integer, required

## Other responses

- `401` — The provided authentication token does not have permissions for some of the requested resources

---

[API](https://skmtc.dev/voiceflow/apis/general-runtime.md) · [All operations](https://skmtc.dev/voiceflow/apis/general-runtime/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/voiceflow/general-runtime/revisions/6b1c4f778c56/schema)