API Reference

Query grouped results of a completed token usage report

get
https://go.v7labs.com/api/workspaces//reports/token_reports//results

Aggregates a completed report's rows to a UI-ready grain (workflows,
workflow properties, chats, or users) and supports search, filtering,
sorting, and cursor pagination over the grouped rows.

Search, provider/model, chat-type, entity-id, and deleted-status filters
apply before aggregation, so grouped totals reflect the selected
subset. min_total_tokens and min_estimated_cost_usd apply to the
grouped totals. Budget filters and budget enrichment (agents view) use
the workflows' live active budgets, not the report's historical window.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
uuid
required
^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
uuid
required
^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Query Params
string
enum
required

The UI grain to aggregate the report's rows to:

  • agents: one row per root workflow (agent reports)
  • agent_properties: one row per workflow/property pair (agent reports grouped by property)
  • chats: one row per case (chat reports grouped by case)
  • users: one row per user (user_usage reports)
Allowed:
string
length ≤ 1024

Case-insensitive search over the view's snapshot labels: workflow names for
agents, workflow/property names for agent_properties, case names, user
emails, and agent names for chats, and user emails for users.
Trimmed; empty input means no search. At most 1024 characters.

providers
array of strings

Only include usage recorded for these providers (OR semantics). Grouped totals cover only the selected providers. Not supported for the users view.

TokenReports.ResultsProviders
Allowed:
models
array of strings

Only include usage recorded for these models (OR semantics). Not supported for the users view.

TokenReports.ResultsModels
chat_types
array of strings

Only include chats with these chat types (chats view only).

TokenReports.ResultsChatTypes
Allowed:
project_ids
array of objects

Only include groups for these entity ids.

TokenReports.ResultsIdFilter
case_ids
array of objects

Only include groups for these entity ids.

TokenReports.ResultsIdFilter
user_ids
array of objects

Only include groups for these entity ids.

TokenReports.ResultsIdFilter
string
enum
Defaults to all

Filter groups by the current existence of the view's primary entity
(workflow, property, case, or workspace membership), checked live at query
time rather than from the report snapshot.

Rejected with a validation error for reports with more than 25,000
distinct groups in the view.

Allowed:
boolean

Agents view only. When true, only workflows with at least one active budget; when false, only workflows without any active budget.

float
≥ 0

Agents view only. Budget usage percentage bound over the workflow's highest-usage active budget. The minimum bound is inclusive, the maximum bound is exclusive. Percentages can exceed 100.

float
≥ 0

Agents view only. Budget usage percentage bound over the workflow's highest-usage active budget. The minimum bound is inclusive, the maximum bound is exclusive. Percentages can exceed 100.

integer
≥ 0

Only include groups whose summed total tokens are at least this value.

float
≥ 0

Only include groups whose summed estimated cost is at least this value.

boolean
Defaults to false

When true, includes a summary over the complete filtered grouped result (not only the current page). Fetch it once per filter change.

order_by
array of strings | null

Fields to order by. Availability depends on the view:

  • all views: id
  • agents/agent_properties/chats: name, total_tokens, go_input_tokens, go_output_tokens, estimated_cost_usd
  • agents: property_count, contributing_users_count
  • agent_properties: contributing_users_count
  • users: email, active_days_count, edited_agent_fields_count, chats_started_count,
    chat_messages_sent_count, chat_go_input_tokens, chat_go_output_tokens,
    chat_estimated_cost_usd, input_fields_written_count, corrections_count

Defaults: descending total_tokens for agents and agent_properties, descending
estimated_cost_usd for chats, and descending active_days_count for users.

TokenReports.ResultsOrderBy
order_directions
array of strings | null

List of order directions for the fields in order_by. Report results only support asc and desc.

TokenReports.ResultsOrderDirections
Allowed:
integer | null

The number of records to return after the provided cursor; used in combination with after

integer | null

The number of records to return for before the provided cursor; used in combination with before

string | null

A base64 encoded value representing a cursor, or an element ID if applicable

string | null

A base64 encoded value representing a cursor, or an element ID if applicable

Responses

Callback

Updated about 7 hours ago

Did this page help you?
Language
Credentials
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 7 hours ago

Did this page help you?