---
title: "Get Usage"
method: GET
path: "/v1/usage/"
tags: ["Usage"]
---

# Get Usage

`GET /v1/usage/`

## Query parameters

- `workspace_uuid` string, nullable
- `date_from` string, date, nullable — Start date for filtering free user score runs
- `date_to` string, date, nullable — End date for filtering free user score runs
- `billing_cycle_uuid` string, nullable — Specific billing cycle UUID to retrieve

## Response `200`

OK

- UsageResponseSchema
  - `billing_cycles` BillingCycleUsageSchema[], nullable
    - `billing_cycle_uuid` string, required
    - `billing_cycle_start_date` string, date, required
    - `billing_cycle_end_date` string, date, required
    - `paid_amount_usd` union, required
      - number
      - string
    - `pricing_model` string, required
    - `usage_breakdown` UsageBreakdownSchema — Detailed usage breakdown by pricing dimensions.
      - `tests_created` integer, required
      - `total_prompts_generated` integer, required
      - `score_runs_completed` integer, required
      - `total_prompts_scored` integer, required
      - `usage_events` UsageEventSchema[], required
        - `date` string, date-time, required
        - `name` string, required
        - `operation` string, required
        - `quantity` integer, required
        - `eval_type` string, nullable
        - `is_jailbreak` boolean, required
        - `modality` string, required
        - `has_ground_truth` boolean, required
        - `cost` union, required
          - number
          - string
        - `notes` string, nullable
        - `eval_uuid` string, nullable
        - `eval_run_uuid` string, nullable
        - `workspace_uuid` string, nullable
        - `unit_price` union
          - number
          - string
        - `price_rule_uuid` string, nullable
        - `workspace_name` string, nullable
        - `created_by` string, nullable
        - `rule_metric` string, nullable
      - `pricing_rule_usage` PricingRuleUsageSchema[], required
        - `rule_name` string, required
        - `rule_uuid` string, required
        - `priority` integer, required
        - `metric` string, nullable, required
        - `operation` string, nullable, required
        - `modality` string, nullable, required
        - `is_jailbreak` boolean, nullable, required
        - `has_ground_truth` boolean, nullable, required
        - `quantity` integer, required
        - `unit_price` union, required
          - number
          - string
        - `total_cost` union, required
          - number
          - string
      - `costs` object, required
      - `pricing_model` string, required
    - `pricing_rules_count` integer, nullable
    - `total_usage` union
      - number
      - string
    - `credits_available` union
      - number
      - string
    - `credits_used` union
      - number
      - string
    - `balance_remaining` union
      - number
      - string
    - `workspace_groups` WorkspaceGroupUsageSchema[], nullable
      - `group_name` string, required
      - `workspaces` string[], required
      - `total_cost` union, required
        - number
        - string
      - `use_credits` boolean, required
      - `credits_used` union
        - number
        - string
      - `balance_remaining` union
        - number
        - string
  - `free_score_runs` ScoreRunOutSchema[], nullable
    - `score_run_uuid` string, required
    - `score_run_status` 'record_created' | 'image_uploading' | 'scoring' | 'finished' | 'failed', required
    - `test` TestOutSchema, required
      - `test_uuid` string, required
      - `test_name` string, required
      - `test_status` 'record_created' | 'generating_questions' | 'finished' | 'failed', required — Test status.
      - `test_type` string, required
      - `organization_name` string, nullable
      - `num_test_questions` integer, nullable
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `test_system_prompt` string, nullable
      - `test_policy` string, nullable
      - `knowledge_base` string, nullable
      - `additional_instructions` string, nullable
      - `is_jailbreak` boolean
      - `modality` 'text' | 'image' | 'video' — Content type for AI interactions.
      - `test_examples` ExampleOutSchema[], nullable
        - `example_uuid` string, required
        - `example_text` string, required
        - `explanation` string, nullable
        - `example_type` 'good' | 'bad', required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `remaining_score_runs` integer, nullable
    - `price` number, required
    - `price_adjustment_note` string, nullable
    - `created_by` UserOutSchema
      - `email` string, required
      - `organization` OrganizationOutSchema
        - `org_uuid` string, required
        - `name` string, required
      - `workspace` WorkspaceOutSchema
        - `workspace_uuid` string, nullable
        - `name` string, nullable
        - `organization_name` string, nullable
        - `organization_uuid` string, nullable
      - `org_admin_emails` string[], nullable
      - `is_admin` boolean, required
      - `is_impersonating` boolean, required
      - `feature_flags` FeatureFlags, required
        - `enable_dashboard` boolean, required
    - `score_run_examples` ScoringExampleOutSchema[], nullable
      - `example_uuid` string, required
      - `question_text` string, required
      - `answer_text` string, required
      - `explanation` string, required
      - `example_type` 'pass' | 'fail', required
    - `pass_rate` number, nullable
    - `workspace_uuid` string, nullable
    - `workspace_name` string, nullable
  - `test_type_displays` object, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/aymara-ai/apis/aymara-api.md) · [All operations](https://skmtc.net/aymara-ai/apis/aymara-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aymara-ai/aymara-api/revisions/0cb64ef11adf/schema)