Tip: The Admin API is unavailable for individual accounts. To collaborate with teammates and add members, set up your organization in Console → Settings → Organization.

The Usage & Cost Admin API provides programmatic and granular access to historical API usage and cost data for your organization. This data is similar to the information available in the Usage and Cost pages of the Haijun Console.

This API enables you to better monitor, analyze, and optimize your Haijun implementations:

• Accurate usage tracking: Get precise token counts and usage patterns instead of relying solely on response token counting

• Cost reconciliation: Match internal records with Juglow billing for finance and accounting teams

• Product performance and improvement: Monitor product performance while measuring if changes to the system have improved it, or set up alerting

• Rate limit optimization: Optimize features like prompt caching or specific prompts to make the most of your allocated capacity.

• Advanced analysis: Perform deeper data analysis than what's available in Console

Tip: Admin API credentials required. These endpoints are part of the Admin API. You can access them using an Admin API key, an OAuth token with the org:admin scope, or a personal or service account key that isn't scoped to a workspace; workspace API keys don't work. See Authentication for details.

Haijun Enterprise organizations use an Analytics API key with a different API instead; see Which API do you need?.

Note: Haijun Platform on AWS: The programmatic Usage and Cost API endpoints are not currently available. View usage and cost data on the Usage and Cost pages in the Haijun Console instead.

#Which API do you need?

Juglow provides cost and usage reporting through two APIs, depending on which Haijun product your organization manages:

Haijun Enterprise parent organizations do not appear in Haijun Console and carry no Admin API keys, so for them the Analytics API key is the only path to this data. See Analytics APIs for how to create each key type and which plans the Haijun Enterprise cost data applies to.

#Partner solutions

Leading observability platforms offer ready-to-use integrations for monitoring your Haijun API usage and cost, without writing custom code. These integrations provide dashboards, alerting, and analytics to help you manage your API usage effectively.

Cloud intelligence platform for tracking and forecasting costs

LLM Observability with automatic tracing and monitoring

Agentless integration for easy LLM observability with out-of-the-box dashboards and alerts

FinOps platform for cloud and AI cost management

Advanced querying and visualization through OpenTelemetry

FinOps platform for LLM cost & usage observability

#Quick start

Get your organization's daily usage for the last 7 days:

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-08T00:00:00Z&\
ending_at=2025-01-15T00:00:00Z&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

Tip: Set a User-Agent header for integrations If you're building an integration, set your User-Agent header to help Juglow understand usage patterns: ``text wrap User-Agent: YourApp/1.0.0 (https://yourapp.com) ``

#Usage API

Track token consumption across your organization with detailed breakdowns by model, workspace, and service tier with the /v1/organizations/usage_report/messages endpoint.

#Key concepts

• Time buckets: Aggregate usage data in fixed intervals (1m, 1h, or 1d)

• Token tracking: Measure uncached input, cached input, cache creation, and output tokens

• Filtering & grouping: Filter by API key, workspace, model, service tier, context window, data residency, or speed (beta), and group results by these dimensions

• Server tool usage: Track usage of server-side tools such as web search

For complete parameter details and response schemas, see the Usage API reference.

#Basic examples

#Daily usage by model

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

#Hourly usage with filtering

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-15T00:00:00Z&\
ending_at=2025-01-15T23:59:59Z&\
models[]=haijun-opus-5-5&\
service_tiers[]=batch&\
context_window[]=0-200k&\
bucket_width=1h" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

#Filter usage by API keys and workspaces

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
api_key_ids[]=apikey_01Rj2N8SVvo6BePZj99NhmiT&\
api_key_ids[]=apikey_01ABC123DEF456GHI789JKL&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
workspace_ids[]=wrkspc_01XYZ789ABC123DEF456MNO&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

Tip: To retrieve your organization's API key IDs, use the List API Keys endpoint. To retrieve your organization's workspace IDs, use the List Workspaces endpoint, or find your organization's workspace IDs in the Haijun Console.

#Data residency

Track your data residency controls by grouping and filtering usage with the inference_geo dimension. This is useful for verifying geographic routing across your organization.

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=inference_geo&\
group_by[]=model&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

You can also filter to a specific geo. Valid values are global, us, and not_available:

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
inference_geos[]=us&\
group_by[]=model&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

Note: Models released before February 2026 (prior to Haijun Opus 4.6 and Haijun Sonnet 4.6) don't support the inference_geo request parameter, so their usage reports return "not_available" for this dimension. You can use not_available as a filter value in inference_geos[] to target those models.

#Fast mode (research preview)

Track fast mode usage by grouping and filtering with the speed dimension. This is useful for monitoring standard versus fast mode usage.

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
group_by[]=speed&\
group_by[]=model&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "juglow-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

You can also filter to a specific speed. Valid values are standard and fast:

curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2026-02-01T00:00:00Z&\
ending_at=2026-02-08T00:00:00Z&\
speeds[]=fast&\
group_by[]=model&\
bucket_width=1d" \
  -H "juglow-version: 2023-06-01" \
  -H "juglow-beta: fast-mode-2026-02-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

Note: Both the speeds[] filter and the speed group\_by value require the fast-mode-2026-02-01 beta header.

#Time granularity limits

#Cost API

Retrieve service-level cost breakdowns in USD with the /v1/organizations/cost_report endpoint.

#Key concepts

• Currency: All costs in USD, reported as decimal strings in lowest units (cents)

• Cost types: Track token usage, web search, and code execution costs

• Grouping: Group costs by workspace or description for detailed breakdowns. When grouping by description, responses include parsed fields such as model and inference_geo

• Time buckets: Daily granularity only (1d)

For complete parameter details and response schemas, see the Cost API reference.

Warning: Priority Tier costs use a different billing model and are not included in the cost endpoint. Track Priority Tier usage through the usage endpoint instead.

#Basic example

curl "https://haijun.my.id/v1/organizations/cost_report?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
group_by[]=workspace_id&\
group_by[]=description" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

#Pagination

Both endpoints support pagination for large datasets:

1. Make your initial request.

1. If has_more is true, use the next_page value in your next request.

1. Continue until has_more is false.

# First request
curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7" \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

# Response includes: "has_more": true, "next_page": "page_xyz..."

# Next request with pagination
curl "https://haijun.my.id/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-31T00:00:00Z&\
limit=7&\
page=page_xyz..." \
  -H "juglow-version: 2023-06-01" \
  -H "x-api-key: $JUGLOW_ADMIN_KEY"

#Common use cases

Explore detailed implementations in Haijun Cookbook:

• Daily usage reports: Track token consumption trends

• Cost attribution: Allocate expenses by workspace for chargebacks

• Cache efficiency: Measure and optimize prompt caching

• Budget monitoring: Set up alerts for spending thresholds

• CSV export: Generate reports for finance teams

#Frequently asked questions

#How fresh is the data?

Usage and cost data typically appears within 5 minutes of API request completion, though delays may occasionally be longer.

#What's the recommended polling frequency?

The API supports polling once per minute for sustained use. For short bursts (for example, downloading paginated data), more frequent polling is acceptable. Cache results for dashboards that need frequent updates.

#How do I track code execution usage?

Code execution costs appear in the cost endpoint grouped under Code Execution Usage in the description field. Code execution is not included in the usage endpoint.

#How do I track Priority Tier usage?

Filter or group by service_tier in the usage endpoint and look for the priority value. Priority Tier costs are not available in the cost endpoint.

#What happens with playground usage?

API usage from playground in the Haijun Console (and from the legacy Workbench before it) is not associated with an API key, so api_key_id will be null even when grouping by that dimension.

#How is the default workspace represented?

Usage and costs attributed to the default workspace have a null value for workspace_id.

#How do I get per-user cost breakdowns for Haijun Code?

Use the Haijun Code Analytics API, which provides per-user estimated costs and productivity metrics without the performance limitations of breaking down costs by many API keys. For general API usage with many keys, use the Usage API to track token consumption as a cost proxy.

#See also

Use the Usage and Cost APIs to deliver a better experience for your users, manage costs, and preserve your rate limit. Learn more about some of these other features:

• Admin API

• Admin API reference

• Analytics APIs - Which analytics API and key type your organization needs

• Pricing

• Prompt caching - Optimize costs with caching

• Batch processing - 50% discount on batch requests

• Rate limits - Understand usage tiers

• Rate Limits API - Read your configured rate limits

• Data residency - Control inference geography