Organisation stats

Usage and credit for the current billing period. Useful for a “credits remaining” indicator in your own product, or for a pre-flight check before submitting a large batch — running out of credit mid-batch is a normal outcome, but it’s cheaper to know beforehand.

Endpoint

GET /v1/organisation/stats

The organisation is derived from the API key itself — there is nothing to pass.

Example

cURL

curl "https://pagr-prd-api-public.azurewebsites.net/v1/organisation/stats" \
  -H "Authorization: Bearer pagr_prod_xxxxxxxx"

Python

import asyncio
from pagr import PagrApiClient

async def main():
    async with PagrApiClient("pagr_prod_xxxxxxxx") as client:
        stats = await client.get_org_stats()
        print(stats)                       # OrgStats | Acme Inc. (growth) …

        if stats.pages_available != -1 and stats.pages_available < 100:
            print("Running low on page credit")

asyncio.run(main())

TypeScript

import { PagrApiClient } from 'pagr';

const client = new PagrApiClient('pagr_prod_xxxxxxxx');

const stats = await client.getOrgStats();
console.log(stats.organisationName, stats.tier);

if (stats.pagesAvailable !== -1 && (stats.pagesAvailable ?? 0) < 100) {
  console.log('Running low on page credit');
}

Java

import org.example.PagrApiClient;
import org.example.models.OrgStats;

try (PagrApiClient client = new PagrApiClient("pagr_prod_xxxxxxxx")) {
    OrgStats stats = client.getOrgStats();
    System.out.println(stats.getOrganisationName() + " (" + stats.getTier() + ")");

    Integer available = stats.getPagesAvailable();
    if (available != null && available != -1 && available < 100) {
        System.out.println("Running low on page credit");
    }
}

C#

using Pagr.Sdk;

using var client = new PagrApiClient("pagr_prod_xxxxxxxx");

var stats = await client.GetOrgStatsAsync();
Console.WriteLine($"{stats.OrganisationName} ({stats.Tier})");

if (stats.PagesAvailable is { } available && available != -1 && available < 100)
    Console.WriteLine("Running low on page credit");

Ruby

require "pagr"

client = Pagr::Client.new("pagr_prod_xxxxxxxx")

stats = client.org_stats
puts "#{stats.organisation_name} (#{stats.tier})"

available = stats.pages_available
warn "Running low on page credit" if available && available != -1 && available < 100

C++

#include "pagr/PagrApiClient.hpp"

pagr::PagrApiClient client("pagr_prod_xxxxxxxx");

const auto stats = client.get_org_stats();
std::cout << stats.organisation_name.value_or("?") << "\n";

if (stats.pages_available.has_value() && *stats.pages_available != -1
    && *stats.pages_available < 100) {
    std::cout << "Running low on page credit\n";
}

A get_org_stats_async form returning std::future<OrgStats> is also available.

Path parameters

None.

Query parameters

None.

Request body

None — this is a GET.

Response

200:

{
  "organisationName": "Acme Inc.",
  "periodStart": "2026-07-01T00:00:00Z",
  "periodEnd": "2026-07-31T23:59:59Z",
  "tier": "growth",
  "includedRendersPerMonth": 5000,
  "pagesUsedThisPeriod": 1204,
  "pagesAvailable": 3796,
  "includedTokensPerMonth": 200000,
  "tokensUsedThisPeriod": 41000,
  "tokensAvailable": 159000,
  "userCount": 4
}

TODO: Remove the mention of -1, should not appear.

Field	Type	Description
organisationName	string	The organisation the API key belongs to.
periodStart / periodEnd	string (ISO 8601)	The current billing period.
tier	string	The plan tier, e.g. growth.
includedRendersPerMonth	number	Page allowance included in the tier.
pagesUsedThisPeriod	number	Pages consumed so far this period.
pagesAvailable	number	Pages remaining. -1 means unlimited.
includedTokensPerMonth	number	AI token allowance. -1 means unlimited.
tokensUsedThisPeriod	number	AI tokens consumed so far this period.
tokensAvailable	number	AI tokens remaining. -1 means unlimited.
userCount	number	Users in the organisation.

“Pages” is the render-credit unit (rendered document pages); “tokens” are AI tokens consumed by AI-assisted template features. Both have a monthly allowance, an amount used this period, and an amount remaining.

-1 means unlimited, not zero

A value of -1 in pagesAvailable, includedTokensPerMonth or tokensAvailable means unlimited for tiers with no hard cap. Compare against -1 explicitly before doing arithmetic or you’ll report a healthy account as out of credit.

Absent fields stay absent

In every SDK the usage counters are nullable (Optional[int] in Python, int? in C#, std::optional<int> in C++, …) rather than defaulting to 0, so a field the server omits is distinguishable from a genuine zero. Check for null/none before comparing.

No template count

This endpoint doesn’t include a template count. If you need one, list templates via Templates & versions and use the paged result’s total — there’s no shortcut through organisation stats.

SDK reference

SDK	Method
Python	await client.get_org_stats()
TypeScript	await client.getOrgStats()
Java	client.getOrgStats()
C#	await client.GetOrgStatsAsync(cancellationToken)
Ruby	client.org_stats
C++	client.get_org_stats() / get_org_stats_async()

Errors

Status	code	When
401	NotAuthenticated	The API key has no associated organisation.

Everything else is auth/transport only. See Errors for the full table.

Related articles

• Billing — the workspace view of plan and usage.
• Usage — historical usage, beyond the current period.
• Render a document — where the insufficient_credit outcome surfaces.