List usage — Brigg developers

Access & visibility

Allow billing.ListUsage on your API key.

Workspace access by default. Private member data requires approved member delegation through Brigg-Act-As; the key supplies permissions while private ownership and project boundaries remain enforced.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

fromintegerOptional

Epoch ms, inclusive.

tointegerOptional

Epoch ms, inclusive.

Balance, charges and underlying usage

Get billing returns the current workspace balance. List credit ledger returns recent balance movements, newest first: a negative amount deducts credit; a positive amount adds it. The default is 50 rows and the maximum is 500, with no cursor for older pages.

For spending over a period, use List usage. Its from and to values are inclusive Unix millisecond timestamps. Use totals.spent_nok for charged credit: it comes from the credit ledger. The items describe individual credit charges and their activities. Use totals for period spending: item detail can be incomplete. Credit figures are in Norwegian kroner, not minor currency units.

Some plans hide credit information. An authorized member can still receive credit_info_hidden on those plans; changing the key's grants does not expose it. Storage usage is a separate byte quota, not a currency balance.

Response

Returns 200 OK with a JSON body.

This operation has no continuation cursor. An empty items array means no matching visible results were returned.

totalsobjectRequired

Credit deducted in the window, from the credit ledger.

Nested fields

spent_noknumberRequired

Usage cost in Norwegian kroner, not øre.

deductionsnumberRequired

Credit deductions included in this usage report.

by_activityarray of objectRequired

Usage totals grouped by activity.

Item fields

activitystring or nullRequired

Null on a deduction older than the activity column.

spent_noknumberRequired

Usage cost in Norwegian kroner, not øre.

deductionsnumberRequired

Credit deductions included in this usage report.

itemsarray of Usage entryRequired

Individual workspace credit charges within the requested time range; totals give the authoritative spending for that period. This operation has no cursor pagination.

Item fields

idstringRequired

Identifier for this recorded charge.

bundle_idnull or stringRequired

App or content item associated with this charge, when recorded.

timestampnumberRequired

Time this charge was recorded, in Unix milliseconds.

actorstringRequired

Person or automated process responsible for the activity, when recorded.

subtypenull or stringRequired

Activity category associated with this charge, when recorded.

credits_deducted_nokstringRequired

Workspace credit charged for this activity as a decimal string in Norwegian kroner. Null means a charge was not recorded on this row; use totals for authoritative spending.

Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. If Brigg-Act-As is supplied, the key must be authorized to delegate to that member.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying.
403	`credit_info_hidden`	This workspace plan does not expose credit and usage details.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "from": {
      "type": "integer",
      "description": "Epoch ms, inclusive."
    },
    "to": {
      "type": "integer",
      "description": "Epoch ms, inclusive."
    }
  },
  "additionalProperties": false,
  "examples": [
    {}
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "totals": {
      "type": "object",
      "description": "Credit deducted in the window, from the credit ledger.",
      "properties": {
        "spent_nok": {
          "type": "number",
          "description": "Usage cost in Norwegian kroner, not øre."
        },
        "deductions": {
          "type": "number",
          "description": "Credit deductions included in this usage report."
        },
        "by_activity": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "activity": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Null on a deduction older than the activity column."
              },
              "spent_nok": {
                "type": "number",
                "description": "Usage cost in Norwegian kroner, not øre."
              },
              "deductions": {
                "type": "number",
                "description": "Credit deductions included in this usage report."
              }
            },
            "required": [
              "activity",
              "spent_nok",
              "deductions"
            ],
            "additionalProperties": false
          },
          "description": "Usage totals grouped by activity."
        }
      },
      "required": [
        "spent_nok",
        "deductions",
        "by_activity"
      ],
      "additionalProperties": false
    },
    "items": {
      "type": "array",
      "items": {
        "title": "Usage entry",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier for this recorded charge.",
            "examples": [
              "usage_123"
            ]
          },
          "bundle_id": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              }
            ],
            "description": "App or content item associated with this charge, when recorded.",
            "examples": [
              "document_proposal"
            ]
          },
          "timestamp": {
            "type": "number",
            "description": "Time this charge was recorded, in Unix milliseconds.",
            "examples": [
              1794301200000
            ]
          },
          "actor": {
            "type": "string",
            "description": "Person or automated process responsible for the activity, when recorded.",
            "examples": [
              "account_alex"
            ]
          },
          "subtype": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              }
            ],
            "description": "Activity category associated with this charge, when recorded.",
            "examples": [
              "document_generation"
            ]
          },
          "credits_deducted_nok": {
            "type": "string",
            "description": "Workspace credit charged for this activity as a decimal string in Norwegian kroner. Null means a charge was not recorded on this row; use totals for authoritative spending.",
            "examples": [
              "0.10"
            ]
          }
        },
        "required": [
          "id",
          "bundle_id",
          "timestamp",
          "actor",
          "subtype",
          "credits_deducted_nok"
        ],
        "additionalProperties": false
      },
      "description": "Individual workspace credit charges within the requested time range; totals give the authoritative spending for that period. This operation has no cursor pagination."
    }
  },
  "required": [
    "items",
    "totals"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "totals": {
        "spent_nok": 0.1,
        "deductions": 1,
        "by_activity": []
      },
      "items": [
        {
          "id": "usage_123",
          "bundle_id": "document_proposal",
          "timestamp": 1794301200000,
          "actor": "account_alex",
          "subtype": "document_generation",
          "credits_deducted_nok": "0.10"
        }
      ]
    }
  ]
}

Try the request

Use your API key in a server environment.

Act as a memberRequires administrator-approved delegation.

Fictional values. Replace IDs and business details with values from your workspace.

Request

cURL

curl 'https://api.brigg.app/v1/operations/billing.ListUsage' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

TypeScript

const response = await fetch("https://api.brigg.app/v1/operations/billing.ListUsage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {}
request = Request(
    "https://api.brigg.app/v1/operations/billing.ListUsage",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

cURL

curl 'https://api.brigg.app/v1/operations/billing.ListUsage' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/billing.ListUsage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {}
request = Request(
    "https://api.brigg.app/v1/operations/billing.ListUsage",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "totals": {
    "spent_nok": 0.1,
    "deductions": 1,
    "by_activity": []
  },
  "items": [
    {
      "id": "usage_123",
      "bundle_id": "document_proposal",
      "timestamp": 1794301200000,
      "actor": "account_alex",
      "subtype": "document_generation",
      "credits_deducted_nok": "0.10"
    }
  ]
}

Illustrative values, not a live response.