API reference
Billing and usage
The plan, credits and usage of the organisation.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| Get billing | GET /api/orgs/{org}/billing | read |
| Start the trial | POST /api/orgs/{org}/billing/trial | admin |
| Add credits | POST /api/orgs/{org}/billing/credits | console only (owner) |
| Get this month's usage | GET /api/orgs/{org}/usage | read |
#Get billing
GET /api/orgs/{org}/billing
Answers the plan, the seats billed, this month's review allowance and the credit balances with their ledger. Prices are set by the server, as agreed for your workspace.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/billing"
Answer (200, application/json)
A Billing object.
{
"plan": "trial",
"trialEndsAt": "2026-11-30T09:30:00.000Z",
"seatPriceUsd": 0,
"seatsBilled": 5,
"reviewsIncluded": 250,
"reviewsUsed": 61,
"overage": false,
"overageReviews": 0,
"coveredByAgreement": false,
"automationCredits": 0,
"pentestCredits": 0,
"hasPaymentMethod": false,
"ledger": [
{
"id": "cr_1b8d4f0a6c27",
"kind": "automation",
"amount": 0,
"reason": "Fix run",
"refId": "run_9e3c1a7d5b02",
"at": "2026-11-16T09:30:00.000Z"
}
]
}
#Start the trial
POST /api/orgs/{org}/billing/trial
Starts the organisation's trial. It needs the services agreement to be accepted in the same request, and can be done once per organisation.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
acceptTerms | boolean | yes | Must be true: it records that the services agreement was accepted. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"acceptTerms":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/billing/trial"
Answer (200, application/json)
A Billing object.
{
"plan": "trial",
"trialEndsAt": "2026-11-30T09:30:00.000Z",
"seatPriceUsd": 0,
"seatsBilled": 5,
"reviewsIncluded": 250,
"reviewsUsed": 61,
"overage": false,
"overageReviews": 0,
"coveredByAgreement": false,
"automationCredits": 0,
"pentestCredits": 0,
"hasPaymentMethod": false,
"ledger": [
{
"id": "cr_1b8d4f0a6c27",
"kind": "automation",
"amount": 0,
"reason": "Fix run",
"refId": "run_9e3c1a7d5b02",
"at": "2026-11-16T09:30:00.000Z"
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | terms_required | acceptTerms is not true. |
| 409 | trial_used | The organisation already used its trial or is on a plan. |
#Add credits
POST /api/orgs/{org}/billing/credits
Adds credits to one of the two balances. This is a stand-in until a payment provider is connected: it works only on a development server, and answers 501 not_configured everywhere else, including the hosted service. Only an owner signed in to the console can call it.
Who may call it: A signed-in owner in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | yes | Which balance to add to: credits for fix runs, or credits for pentests. One of: automation, pentest. |
amount | number | yes | How many credits to add. Greater than 0 and at most 100000. |
Answer (200, application/json)
A Billing object.
{
"plan": "trial",
"trialEndsAt": "2026-11-30T09:30:00.000Z",
"seatPriceUsd": 0,
"seatsBilled": 5,
"reviewsIncluded": 250,
"reviewsUsed": 61,
"overage": false,
"overageReviews": 0,
"coveredByAgreement": false,
"automationCredits": 0,
"pentestCredits": 0,
"hasPaymentMethod": false,
"ledger": [
{
"id": "cr_1b8d4f0a6c27",
"kind": "automation",
"amount": 0,
"reason": "Fix run",
"refId": "run_9e3c1a7d5b02",
"at": "2026-11-16T09:30:00.000Z"
}
]
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 501 | not_configured | The server has no payment provider, which is the case everywhere except a development server. |
| 400 | bad_request | kind is not automation or pentest, or amount is not a number in range. |
#Get this month's usage
GET /api/orgs/{org}/usage
Answers what the organisation has used in the current calendar month (UTC): pull request reviews against the allowance, reviews per author, fix runs and pentests.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/usage"
Answer (200, application/json)
A Usage object.
{
"periodStart": "2026-11-01T00:00:00.000Z",
"periodEnd": "2026-12-01T00:00:00.000Z",
"reviewsIncluded": 250,
"reviewsUsed": 61,
"byDeveloper": [
{
"login": "dana-okafor",
"reviews": 14,
"seat": true
}
],
"automationRuns": 9,
"automationCreditsUsed": 0,
"pentests": 1,
"toolRuns": 4
}
#Objects
The objects the operations above take and return.
#Billing
The organisation's plan, seats, review allowance and credit balances.
| Field | Type | Always present | Description |
|---|---|---|---|
plan | string | yes | The organisation's plan. One of: none, trial, pro, enterprise. |
trialEndsAt | string or null | yes | When the trial ends. Null when no trial was started. |
seatPriceUsd | number | yes | The price of one pull request review seat for a month, as agreed for your workspace. |
seatsBilled | integer | yes | How many seats are billed now. The People page shows the same number. |
reviewsIncluded | integer or null | yes | Pull request reviews included this month, pooled across all seats: the highest number of seats held this month times the reviews each includes. Null when your agreement covers reviews with no pooled quota. |
reviewsUsed | integer | yes | Pull request reviews counted so far this month. |
overage | boolean | yes | True when reviews beyond the included number are allowed. The same switch as overage in the settings. |
overageReviews | integer | yes | Reviews this month beyond the included number. Always 0 when your agreement covers reviews. |
coveredByAgreement | boolean | no | True when the workspace is billed under an agreement, not per seat or per run: there is no review pool, no extra-review charge and no per-run price. |
automationCredits | number | yes | The balance of credits for fix runs. |
pentestCredits | number | yes | The balance of credits for pentests. |
hasPaymentMethod | boolean | yes | True when a payment method is on file. |
ledger | array of CreditEntry | yes | Up to 100 entries of the credit ledger. |
#Usage
What the organisation has used in the current calendar month.
| Field | Type | Always present | Description |
|---|---|---|---|
periodStart | string | yes | The start of the current calendar month, in UTC. |
periodEnd | string | yes | The start of the next calendar month, in UTC. |
reviewsIncluded | integer or null | yes | Pull request reviews included this month, pooled across all seats. Null when your agreement covers reviews with no pooled quota. |
reviewsUsed | integer | yes | Pull request reviews counted so far this month. |
byDeveloper | array of object | yes | Reviews per pull request author, busiest first. Seat holders with no reviews this month are listed with 0. |
byDeveloper[].login | string | yes | The pull request author's code-host login, in lower case. |
byDeveloper[].reviews | integer | yes | Reviews counted for this author this month. |
byDeveloper[].seat | boolean | yes | True when the member with this code-host login holds a seat. False for bots and people who are not members: only members take a seat. |
automationRuns | integer | yes | Fix runs started this month. |
automationCreditsUsed | number | yes | Credits spent on fix runs this month. |
pentests | integer | yes | Pentests started this month. |
toolRuns | integer | yes | Scanning tool runs started this month. |
#CreditEntry
One line in the credit ledger.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The entry's id. |
kind | string | yes | Which balance the entry belongs to: credits for fix runs, or credits for pentests. One of: automation, pentest. |
amount | number | yes | The change to the balance. Positive is a top-up or refund, negative is spend. |
reason | string | yes | Why the balance changed. |
refId | string or null | yes | The run or pentest the entry belongs to, when there is one. |
at | string | yes | When it was recorded. |
Nullgap documentation