Aggregated usage metrics

curl --request GET \
  --url https://api.aurous-labs.com/v1/usage \
  --header 'X-Api-Key: <api-key>'

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.aurous-labs.com/v1/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "object": "usage.bucket",
      "bucket_start": "2026-05-07T00:00:00Z",
      "bucket_end": "2026-05-08T00:00:00Z",
      "groups": [
        {
          "key": {
            "status": "succeeded",
            "model": "aurous-grow-2.0-pro",
            "api_key_id": "key_01HVABCDEFGHJKMNPQRSTVWXYZ"
          },
          "metrics": {
            "request_count": 142,
            "successful_count": 142,
            "failed_count": 0,
            "cancelled_count": 0,
            "credits_used": 14.12,
            "duration_ms_p50": 1820,
            "duration_ms_p95": 4310,
            "image_count": 142,
            "video_seconds": 0,
            "total_input_tokens": 1234,
            "total_output_tokens": 5678
          }
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

Usage analytics

Aggregated usage metrics

Time-bucketed aggregates of every generation your team has dispatched.

Buckets are returned newest-first. Pass bucket_width to control the bucket size; pass group_by[] to slice each bucket by status, key, user, or modality.

Idempotent: GET is naturally safe to retry; no Idempotency-Key is required.

Pagination is opaque-cursor (page_token); the cursor expires 24h after issue and is invalidated when query parameters change between pages.

Headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After (on 429) are returned on every response.

GET

usage

Aggregated usage metrics

curl --request GET \
  --url https://api.aurous-labs.com/v1/usage \
  --header 'X-Api-Key: <api-key>'

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.aurous-labs.com/v1/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aurous-labs.com/v1/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aurous-labs.com/v1/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aurous-labs.com/v1/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "object": "usage.bucket",
      "bucket_start": "2026-05-07T00:00:00Z",
      "bucket_end": "2026-05-08T00:00:00Z",
      "groups": [
        {
          "key": {
            "status": "succeeded",
            "model": "aurous-grow-2.0-pro",
            "api_key_id": "key_01HVABCDEFGHJKMNPQRSTVWXYZ"
          },
          "metrics": {
            "request_count": 142,
            "successful_count": 142,
            "failed_count": 0,
            "cancelled_count": 0,
            "credits_used": 14.12,
            "duration_ms_p50": 1820,
            "duration_ms_p95": 4310,
            "image_count": 142,
            "video_seconds": 0,
            "total_input_tokens": 1234,
            "total_output_tokens": 5678
          }
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "doc_url": "https://docs.aurous-labs.com/errors#balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2VNABCDEFGHJKM",
    "param": "prompt"
  }
}

Authorizations

X-Api-Key

string

header

required

Your team API key (starts with al_live_).

Headers

Aurous-Version

string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-07-16 for unauthenticated requests.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-07-16"

Query Parameters

start_time

string

required

Inclusive lower bound (RFC 3339).

Example:

"2026-04-08T00:00:00Z"

end_time

string

Exclusive upper bound. Defaults to now.

Example:

"2026-05-08T00:00:00Z"

bucket_width

enum<string>

Bucket size. Default 1d. Each width has a max range cap.

Available options:

1m,

5m,

15m,

1h,

1d,

7d

group_by

enum<string>[]

Optional grouping dims (max 2).

Available options:

status,

api_key_id,

user_id,

type,

model

status

string[]

Filter by status. Comma-separated or repeated. Allowed: pending, processing, succeeded, failed, cancelled (legacy alias completed = succeeded).

type

string[]

Filter by inference type. Comma-separated or repeated.

api_key_id

string[]

Filter by opaque API-key id (key_).

user_id

string[]

Filter by opaque user id (usr_).

lora_id

string[]

Filter by opaque LoRA id (lora_).

character_id

string

Single character filter (char_).

Example:

"char_01HVABCDEFGHJKMNPQRSTVWXYZ"

model

string[]

Filter by public model slug (e.g. aurous-grow-2.0-pro). Comma-separated or repeated. Unknown slugs return 400 invalid_filter.

Example:

"aurous-grow-2.0-pro,aurous-embed-vision-1.0"

limit

number

Items per page (1-100, default 24).

Required range: 1 <= x <= 100

Example:

24

page_token

string

Opaque cursor returned in next_page from a prior call. 24h TTL.

Example:

"eyJ2IjoxLCJxZiI6Ii4uLiJ9"

Response

Usage aggregates (newest first).

object

enum<string>

required

Discriminator

Available options:

list

Example:

"list"

data

object[]

required

Buckets in bucket_start DESC order.

Show child attributes

has_more

boolean

required

True when more buckets exist beyond this page.

Example:

false

next_page

object | null

required

Pass as ?page_token=<token> on the next request. Opaque base64; tied to the original query fingerprint. Null when has_more=false. 24h expiry.

Example:

null

Get started

Guides

Concepts

API Reference

Resources

Aggregated usage metrics

Authorizations

Headers

Query Parameters

Response