Usage

Retrieve scan usage statistics for your organization, broken down by billing period. Includes total scan counts and tier breakdowns (green, yellow, red).

GET

/v1/usage

Get scan usage statistics with optional date filtering.

Query Parameters

Parameter	Type	Required	Description
`from`	string	No	Start date filter (YYYY-MM-DD). Returns periods starting on or after this date.
`to`	string	No	End date filter (YYYY-MM-DD). Returns periods starting on or before this date.

Response

200 OK

{
  "periods": [
    {
      "id": "uuid",
      "period_start": "2026-02-01T00:00:00Z",
      "period_end": "2026-02-28T23:59:59Z",
      "scan_count": 1240,
      "green_count": 980,
      "yellow_count": 210,
      "red_count": 50
    },
    {
      "id": "uuid",
      "period_start": "2026-01-01T00:00:00Z",
      "period_end": "2026-01-31T23:59:59Z",
      "scan_count": 870,
      "green_count": 650,
      "yellow_count": 180,
      "red_count": 40
    }
  ],
  "totals": {
    "scan_count": 2110,
    "green_count": 1630,
    "yellow_count": 390,
    "red_count": 90
  }
}

Response Fields

Parameter	Type	Required	Description
`periods`	Period[]	Yes	Array of usage periods, most recent first
`totals`	object	Yes	Aggregated totals across all returned periods
`totals.scan_count`	number	Yes	Total scans across all periods
`totals.green_count`	number	Yes	Total green-tier results
`totals.yellow_count`	number	Yes	Total yellow-tier results
`totals.red_count`	number	Yes	Total red-tier results

Examples

SDK

// Get all usage
const { totals, periods } = await armor.getUsage();
console.log(totals.scan_count); // 2110

// Get usage for a specific month
const jan = await armor.getUsage({
  from: '2026-01-01',
  to: '2026-01-31',
});

cURL

curl "https://indigiarmor.com/v1/usage?from=2026-01-01" \
  -H "Authorization: Bearer ia_sk_..."