> ## Documentation Index
> Fetch the complete documentation index at: https://developer.revise.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get usage

> Account-scoped, receipt-based aggregation by completion time, including succeeded, failed and cancelled requests with settled receipts; pending requests are excluded. Filters combine with AND. No document, comment, prompt, artifact, supplier-cost or margin data is read or returned. Totals cover the entire filtered interval and reconcile with receipt charges, not current rates. Model/provider dimensions describe the requested configuration. No implied blended rates are returned. Money uses exact decimal strings. Rows sort by bucket then dimensions; each request contributes once. More than 1000 rows returns 422 with no partial report: narrow filters/range, reduce dimensions or use coarser buckets. Queries time out after five seconds (503). Reports use one database statement snapshot; no snapshot cursor or pagination. Fixed past completion windows stabilize once settled; future/open windows grow as requests finish. Unknown, empty or repeated parameters return 400; empty metadata filter values are allowed.

## TypeScript

```ts theme={null}
import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.usage.get({ start: "2026-09-01T00:00:00Z", end: "2026-10-01T00:00:00Z" });
```


## OpenAPI

````yaml openapi/revise-api.json GET /v1/usage
openapi: 3.1.0
info:
  title: Revise API
  version: 0.1.0
  description: >-
    Queued document prompting and file conversion. Conversion supports the same
    formats as revise.io/converter, including semantic PDF/image scanning. USD
    responses are exact decimal strings. Same-origin downloads require Bearer
    auth. Account provider keys (BYOK) are pinned at admission. Request content
    expires 24 hours after terminal completion; encrypted artifacts use compact
    JWE RSA-OAEP-256/A256GCM.
servers:
  - url: https://revise.io/api
security:
  - apiKey: []
paths:
  /v1/usage:
    get:
      summary: Aggregate settled account usage and customer charges
      description: >-
        Account-scoped, receipt-based aggregation by completion time, including
        succeeded, failed and cancelled requests with settled receipts; pending
        requests are excluded. Filters combine with AND. No document, comment,
        prompt, artifact, supplier-cost or margin data is read or returned.
        Totals cover the entire filtered interval and reconcile with receipt
        charges, not current rates. Model/provider dimensions describe the
        requested configuration. No implied blended rates are returned. Money
        uses exact decimal strings. Rows sort by bucket then dimensions; each
        request contributes once. More than 1000 rows returns 422 with no
        partial report: narrow filters/range, reduce dimensions or use coarser
        buckets. Queries time out after five seconds (503). Reports use one
        database statement snapshot; no snapshot cursor or pagination. Fixed
        past completion windows stabilize once settled; future/open windows grow
        as requests finish. Unknown, empty or repeated parameters return 400;
        empty metadata filter values are allowed.
      operationId: getUsage
      parameters:
        - name: start
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Inclusive completion time. Defaults to 30 days before end. RFC3339
            timezone required.
        - name: end
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Exclusive completion time. Defaults to now. Range must be positive
            and at most 366 days; hourly ranges at most 31 days.
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - hour
              - day
              - month
              - none
            default: day
          description: >-
            UTC calendar buckets, or no time bucketing. Empty time buckets are
            omitted.
        - name: group_by
          in: query
          schema:
            type: string
          description: >-
            Comma-separated distinct dimensions, maximum three: api_key_id,
            provider, model, status, document_access, pricing_version,
            metadata.KEY (KEY 1–64 bytes). Missing values form null groups.
            Example: api_key_id,metadata.customer.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - succeeded
              - failed
              - cancelled
        - name: conversation_id
          in: query
          schema:
            type: string
          description: Exact conv_ ID.
        - name: api_key_id
          in: query
          schema:
            type: string
          description: >-
            Exact key_ ID of the submitting key. Older unattributed prompts do
            not match.
        - name: metadata
          in: query
          style: deepObject
          explode: true
          schema:
            type: object
            maxProperties: 16
            additionalProperties:
              type: string
              maxLength: 512
          description: >-
            Exact AND matches, e.g. metadata[customer]=Acme. Keys up to 64
            bytes; values up to 512 bytes.
        - name: provider
          in: query
          schema:
            type: string
            enum:
              - openai
              - anthropic
              - xai
              - gemini
          description: Exact requested provider. Gemini uses the public name gemini.
        - name: model
          in: query
          schema:
            type: string
            maxLength: 256
          description: Exact requested model ID; use with provider to disambiguate.
        - name: document_access
          in: query
          schema:
            type: string
            enum:
              - read
              - comment
              - edit
          description: Exact admitted document permission; not inferred from tool behavior.
        - name: pricing_version
          in: query
          schema:
            type: string
            maxLength: 256
          description: Exact pricing version pinned at admission.
      responses:
        '200':
          description: Complete filtered usage report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReport'
              example:
                start: '2026-09-06T00:00:00Z'
                end: '2026-09-08T00:00:00Z'
                time_basis: completed_at
                bucket: day
                group_by:
                  - metadata.customer
                totals:
                  request_count: 5
                  tool_cpu_seconds: '5.000000'
                  inference_usage:
                    input_tokens: 6000
                    cached_input_tokens: 2000
                    cache_creation_input_tokens: 0
                    output_tokens: 1000
                    web_search_requests_by_unit:
                      calls: 5
                      queries: 0
                      grounded_prompts: 0
                  cost:
                    total_usd: '0.305000000'
                    itemized:
                      base_fee_usd: '0.250000000'
                      cpu_fee_usd: '0.005000000'
                      inference_fee_usd: '0.050000000'
                data:
                  - bucket_start: '2026-09-06T00:00:00Z'
                    bucket_end: '2026-09-07T00:00:00Z'
                    dimensions:
                      metadata.customer: acme
                    request_count: 2
                    tool_cpu_seconds: '2.000000'
                    inference_usage:
                      input_tokens: 2400
                      cached_input_tokens: 800
                      cache_creation_input_tokens: 0
                      output_tokens: 400
                      web_search_requests_by_unit:
                        calls: 2
                        queries: 0
                        grounded_prompts: 0
                    cost:
                      total_usd: '0.122000000'
                      itemized:
                        base_fee_usd: '0.100000000'
                        cpu_fee_usd: '0.002000000'
                        inference_fee_usd: '0.020000000'
                  - bucket_start: '2026-09-07T00:00:00Z'
                    bucket_end: '2026-09-08T00:00:00Z'
                    dimensions:
                      metadata.customer: acme
                    request_count: 3
                    tool_cpu_seconds: '3.000000'
                    inference_usage:
                      input_tokens: 3600
                      cached_input_tokens: 1200
                      cache_creation_input_tokens: 0
                      output_tokens: 600
                      web_search_requests_by_unit:
                        calls: 3
                        queries: 0
                        grounded_prompts: 0
                    cost:
                      total_usd: '0.183000000'
                      itemized:
                        base_fee_usd: '0.150000000'
                        cpu_fee_usd: '0.003000000'
                        inference_fee_usd: '0.030000000'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UsageReport:
      type: object
      additionalProperties: false
      required:
        - start
        - end
        - time_basis
        - bucket
        - group_by
        - totals
        - data
      properties:
        start:
          type: string
          format: date-time
          example: '2026-09-06T00:00:00Z'
        end:
          type: string
          format: date-time
          example: '2026-09-08T00:00:00Z'
        time_basis:
          const: completed_at
          example: completed_at
        bucket:
          enum:
            - hour
            - day
            - month
            - none
          example: day
        group_by:
          type: array
          maxItems: 3
          uniqueItems: true
          items:
            type: string
          example:
            - metadata.customer
        totals:
          $ref: '#/components/schemas/UsageTotals'
          example:
            request_count: 5
            tool_cpu_seconds: '5.000000'
            inference_usage:
              input_tokens: 6000
              cached_input_tokens: 2000
              cache_creation_input_tokens: 0
              output_tokens: 1000
              web_search_requests_by_unit:
                calls: 5
                queries: 0
                grounded_prompts: 0
            cost:
              total_usd: '0.305000000'
              itemized:
                base_fee_usd: '0.250000000'
                cpu_fee_usd: '0.005000000'
                inference_fee_usd: '0.050000000'
        data:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/UsageBucket'
          example:
            - bucket_start: '2026-09-06T00:00:00Z'
              bucket_end: '2026-09-07T00:00:00Z'
              dimensions:
                metadata.customer: acme
              request_count: 2
              tool_cpu_seconds: '2.000000'
              inference_usage:
                input_tokens: 2400
                cached_input_tokens: 800
                cache_creation_input_tokens: 0
                output_tokens: 400
                web_search_requests_by_unit:
                  calls: 2
                  queries: 0
                  grounded_prompts: 0
              cost:
                total_usd: '0.122000000'
                itemized:
                  base_fee_usd: '0.100000000'
                  cpu_fee_usd: '0.002000000'
                  inference_fee_usd: '0.020000000'
            - bucket_start: '2026-09-07T00:00:00Z'
              bucket_end: '2026-09-08T00:00:00Z'
              dimensions:
                metadata.customer: acme
              request_count: 3
              tool_cpu_seconds: '3.000000'
              inference_usage:
                input_tokens: 3600
                cached_input_tokens: 1200
                cache_creation_input_tokens: 0
                output_tokens: 600
                web_search_requests_by_unit:
                  calls: 3
                  queries: 0
                  grounded_prompts: 0
              cost:
                total_usd: '0.183000000'
                itemized:
                  base_fee_usd: '0.150000000'
                  cpu_fee_usd: '0.003000000'
                  inference_fee_usd: '0.030000000'
      example:
        start: '2026-09-06T00:00:00Z'
        end: '2026-09-08T00:00:00Z'
        time_basis: completed_at
        bucket: day
        group_by:
          - metadata.customer
        totals:
          request_count: 5
          tool_cpu_seconds: '5.000000'
          inference_usage:
            input_tokens: 6000
            cached_input_tokens: 2000
            cache_creation_input_tokens: 0
            output_tokens: 1000
            web_search_requests_by_unit:
              calls: 5
              queries: 0
              grounded_prompts: 0
          cost:
            total_usd: '0.305000000'
            itemized:
              base_fee_usd: '0.250000000'
              cpu_fee_usd: '0.005000000'
              inference_fee_usd: '0.050000000'
        data:
          - bucket_start: '2026-09-06T00:00:00Z'
            bucket_end: '2026-09-07T00:00:00Z'
            dimensions:
              metadata.customer: acme
            request_count: 2
            tool_cpu_seconds: '2.000000'
            inference_usage:
              input_tokens: 2400
              cached_input_tokens: 800
              cache_creation_input_tokens: 0
              output_tokens: 400
              web_search_requests_by_unit:
                calls: 2
                queries: 0
                grounded_prompts: 0
            cost:
              total_usd: '0.122000000'
              itemized:
                base_fee_usd: '0.100000000'
                cpu_fee_usd: '0.002000000'
                inference_fee_usd: '0.020000000'
          - bucket_start: '2026-09-07T00:00:00Z'
            bucket_end: '2026-09-08T00:00:00Z'
            dimensions:
              metadata.customer: acme
            request_count: 3
            tool_cpu_seconds: '3.000000'
            inference_usage:
              input_tokens: 3600
              cached_input_tokens: 1200
              cache_creation_input_tokens: 0
              output_tokens: 600
              web_search_requests_by_unit:
                calls: 3
                queries: 0
                grounded_prompts: 0
            cost:
              total_usd: '0.183000000'
              itemized:
                base_fee_usd: '0.150000000'
                cpu_fee_usd: '0.003000000'
                inference_fee_usd: '0.030000000'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    UsageTotals:
      type: object
      additionalProperties: false
      required:
        - request_count
        - tool_cpu_seconds
        - inference_usage
        - cost
      properties:
        request_count:
          type: integer
          minimum: 0
          example: 5
        tool_cpu_seconds:
          type: string
          pattern: ^[0-9]+\.[0-9]{6}$
          example: '5.000000'
        inference_usage:
          anyOf:
            - $ref: '#/components/schemas/AggregatedInferenceUsage'
            - type: 'null'
          description: >-
            Null if any receipt in this aggregate lacks inference counters;
            charge totals remain complete. Empty aggregates have zero counters.
          example:
            input_tokens: 6000
            cached_input_tokens: 2000
            cache_creation_input_tokens: 0
            output_tokens: 1000
            web_search_requests_by_unit:
              calls: 5
              queries: 0
              grounded_prompts: 0
        cost:
          $ref: '#/components/schemas/Cost'
      example:
        request_count: 5
        tool_cpu_seconds: '5.000000'
        inference_usage:
          input_tokens: 6000
          cached_input_tokens: 2000
          cache_creation_input_tokens: 0
          output_tokens: 1000
          web_search_requests_by_unit:
            calls: 5
            queries: 0
            grounded_prompts: 0
        cost:
          total_usd: '0.305000000'
          itemized:
            base_fee_usd: '0.250000000'
            cpu_fee_usd: '0.005000000'
            inference_fee_usd: '0.050000000'
    UsageBucket:
      type: object
      additionalProperties: false
      required:
        - bucket_start
        - bucket_end
        - dimensions
        - request_count
        - tool_cpu_seconds
        - inference_usage
        - cost
      properties:
        bucket_start:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-09-06T00:00:00Z'
        bucket_end:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-09-07T00:00:00Z'
        dimensions:
          type: object
          maxProperties: 3
          additionalProperties:
            type:
              - string
              - 'null'
          example:
            metadata.customer: acme
        request_count:
          type: integer
          minimum: 0
          example: 2
        tool_cpu_seconds:
          type: string
          pattern: ^[0-9]+\.[0-9]{6}$
          example: '2.000000'
        inference_usage:
          anyOf:
            - $ref: '#/components/schemas/AggregatedInferenceUsage'
            - type: 'null'
          description: >-
            Null if any receipt in this aggregate lacks inference counters;
            charge totals remain complete. Empty aggregates have zero counters.
          example:
            input_tokens: 2400
            cached_input_tokens: 800
            cache_creation_input_tokens: 0
            output_tokens: 400
            web_search_requests_by_unit:
              calls: 2
              queries: 0
              grounded_prompts: 0
        cost:
          $ref: '#/components/schemas/Cost'
      description: >-
        Only occupied buckets are returned. Bounds are clipped to the requested
        interval. Both bounds are null for bucket=none. Missing dimension values
        are null, distinct from empty strings.
      example:
        bucket_start: '2026-09-06T00:00:00Z'
        bucket_end: '2026-09-07T00:00:00Z'
        dimensions:
          metadata.customer: acme
        request_count: 2
        tool_cpu_seconds: '2.000000'
        inference_usage:
          input_tokens: 2400
          cached_input_tokens: 800
          cache_creation_input_tokens: 0
          output_tokens: 400
          web_search_requests_by_unit:
            calls: 2
            queries: 0
            grounded_prompts: 0
        cost:
          total_usd: '0.122000000'
          itemized:
            base_fee_usd: '0.100000000'
            cpu_fee_usd: '0.002000000'
            inference_fee_usd: '0.020000000'
    AggregatedInferenceUsage:
      type: object
      additionalProperties: false
      required:
        - input_tokens
        - cached_input_tokens
        - cache_creation_input_tokens
        - output_tokens
        - web_search_requests_by_unit
      properties:
        input_tokens:
          type: integer
          minimum: 0
          example: 6000
        cached_input_tokens:
          type: integer
          minimum: 0
          example: 2000
        cache_creation_input_tokens:
          type: integer
          minimum: 0
          example: 0
        output_tokens:
          type: integer
          minimum: 0
          example: 1000
        web_search_requests_by_unit:
          type: object
          additionalProperties: false
          required:
            - calls
            - queries
            - grounded_prompts
          properties:
            calls:
              type: integer
              minimum: 0
            queries:
              type: integer
              minimum: 0
            grounded_prompts:
              type: integer
              minimum: 0
          example:
            calls: 5
            queries: 0
            grounded_prompts: 0
      description: >-
        Input includes cached input and cache creation, which are subsets.
        Output includes reasoning. Includes reported physical turns and
        compaction. Search units are kept separate across providers.
      example:
        input_tokens: 6000
        cached_input_tokens: 2000
        cache_creation_input_tokens: 0
        output_tokens: 1000
        web_search_requests_by_unit:
          calls: 5
          queries: 0
          grounded_prompts: 0
    Cost:
      type: object
      additionalProperties: false
      required:
        - total_usd
        - itemized
      properties:
        total_usd:
          type: string
          pattern: ^[0-9]+\.[0-9]{9}$
          example: '0.305000000'
        itemized:
          type: object
          additionalProperties: false
          required:
            - base_fee_usd
            - cpu_fee_usd
            - inference_fee_usd
          properties:
            base_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.250000000'
            cpu_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.005000000'
            inference_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.050000000'
      example:
        total_usd: '0.305000000'
        itemized:
          base_fee_usd: '0.250000000'
          cpu_fee_usd: '0.005000000'
          inference_fee_usd: '0.050000000'
      description: >-
        Settled customer charges. Itemized base, CPU and inference fees are
        disjoint and sum exactly to total_usd. Inference includes model
        processing and web search. No overlapping platform subtotal. Balances
        and limits are separate from cost.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Revise API key from https://revise.io/console/api-keys. Send
        Authorization: Bearer <key>.

````