Read credits and workspace usage

Use this guide to check how much credit you have left, track usage, or bill your own customers based on their assessment counts.

In Dockt, an Account represents your organization and owns your Workspaces. A Workspace keeps a set of verification cases, documents, and settings separate from other Workspaces. Credits belong to your Account; usage is reported by Workspace. See Accounts and workspaces for more about organizing your integration.

Understand what counts as usage

An Assessment is a verification case for one worker. A Decision is the result Dockt produces when it evaluates that case. One Assessment can receive several Decisions as its information changes.

An Assessment counts as one unit of usage when it first receives a Decision with at least one linked, non-withdrawn Document that has finished processing successfully. The compliance result does not affect this count: an incomplete or non-compliant Decision can still count. Later Decisions, including periodic reassessments, do not add another unit.

Creating an empty Assessment does not count. Neither does an Assessment without a Decision, or one whose Decisions have only failed or withdrawn Documents. If a later Decision meets the document requirement, the Assessment then counts once. Only Assessments created on or after billing activation count; older Assessments remain excluded.

Credits cover usage according to your agreed pricing and allowances. An allowance is an amount available to cover usage, such as prepaid credits or a free trial allocation. It can have an expiry date or apply only to certain Workspaces. Usage covered by free credits still appears in your usage reports.

Use remaining allowances to check available credit, provisional usage to track activity, and finalized monthly statements to calculate charges for your own customers. Assessment counts are not credit deductions or your resale prices.

Before you start

Use an Account-scoped API credential with the account:read permission. A Workspace credential cannot read these endpoints, even for its own Workspace. Keep the credential on your backend. The authentication and permissions reference explains credential scopes and permissions.

Pilot billing periods are calendar months in UTC. Confirm with Dockt that billing is activated for your Account before relying on these reports. Creating an Account does not itself activate billing or add credits. If billing setup is pending, the balance is unavailable, not zero.

Read remaining allowances

Configure your base URL and Account token, then fetch one page of allowances:

export DOCKT_API_BASE_URL='https://api.dockt.com'
export DOCKT_API_TOKEN='REPLACE_WITH_ACCOUNT_BEARER_TOKEN'

curl --fail-with-body \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  "$DOCKT_API_BASE_URL/v1/account/credits?limit=25"

Replace REPLACE_WITH_ACCOUNT_BEARER_TOKEN with your Account API key or access token. The examples in the rest of this guide use these environment variables.

The response’s data.allowances contains data, has_more, and next_cursor. While has_more is true, pass next_cursor as the next request’s cursor query parameter. Each allowance includes its remaining amount, unit, allocation priority, applicability, and schedule of available amounts and dates. A null remaining amount or unit means unavailable. Do not add amounts with different units.

data.overage contains charges not covered by allowances for the current UTC calendar month. Each amount includes its currency unit and invoice status. For example, USD cents are not whole US dollars. An exhausted allowance can show zero with separate overage charges; do not infer a negative credit balance. Dockt continues processing Assessments when allowances are exhausted.

retrieved_at records when the data was read. It does not guarantee that all recent usage is included yet. These endpoints are read-only: you cannot use them to add credits or change allowances.

For all paginated requests in this guide, keep the Account, endpoint, filters, and limit unchanged when using a cursor. Cursors expire after 24 hours; restart from the first page after expiry. The limit can be 1–25 and defaults to 25.

Read provisional Workspace usage

Provisional usage shows the usage reported so far and can change as more usage is processed or corrected. Request a period with an included start and an excluded end. This example covers August 2026 in UTC:

curl --fail-with-body --get \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  --data-urlencode 'starting_at=2026-08-01T00:00:00.000Z' \
  --data-urlencode 'ending_before=2026-09-01T00:00:00.000Z' \
  --data-urlencode 'limit=25' \
  "$DOCKT_API_BASE_URL/v1/account/usage"

Both boundaries must be UTC midnight, with the end after the start and at most 366 days apart. Dockt rejects invalid boundaries instead of rounding them. Add workspace_id to filter one Workspace belonging to your Account.

data.data contains Workspace IDs, the assessment_decision metric, the assessment unit, and quantities represented as decimal strings, such as "12" for 12 billable Assessments. Usage fully covered by credits is included.

Follow data.next_cursor while data.has_more is true. Keep the dates, Workspace filter, and limit unchanged between pages. Read all pages before calculating an Account total.

This endpoint always returns status: "provisional", even for past months. Do not use its quantities as final billing inputs. Use a ready usage statement instead.

Obtain quantities for end-customer billing

A usage statement groups assessment counts by Workspace for a billing period. Use a finalized, ready statement to apply your own prices and bill your customers. First, list your Account’s statements:

curl --fail-with-body \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  "$DOCKT_API_BASE_URL/v1/account/usage-statements?limit=25"

This response uses top-level data, has_more, and next_cursor. Follow all pages to find the required UTC calendar month. A list entry’s status alone does not establish readiness. Fetch its detail using the returned id:

export DOCKT_USAGE_STATEMENT_ID='REPLACE_WITH_RETURNED_STATEMENT_ID'
curl --fail-with-body \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  "$DOCKT_API_BASE_URL/v1/account/usage-statements/$DOCKT_USAGE_STATEMENT_ID"

Replace REPLACE_WITH_RETURNED_STATEMENT_ID with the id from the list entry.

Use the detail only when data.provider_status is FINALIZED and data.ready_for_billing is true. Dockt checks that the UTC calendar month has ended and that the statement’s Workspace counts match the recorded billable Assessments, with no usage still waiting to appear in billing reports. Its quantities include credit-covered usage; credit deductions and currency conversions do not add assessment units. Apply your own prices on your backend.

Store the statement ID with your billing record to avoid charging twice when retrying your own billing workflow. Refetch its current status before using it: DRAFT means not finalized, and VOID means canceled. Neither is ready for billing. When regenerated_from_invoice_id is present, it identifies the earlier statement that was replaced. Use it to handle the correction, not to charge for both statements as separate usage.

Handle unavailable reports

Errors use application/problem+json; inspect the type URI:

• 503 with a type ending in /billing-setup-pending: Your Account’s billing setup is pending. Retry after setup is complete; do not display a zero balance.
• 503 with /billing-unavailable: Retry with increasing delays between attempts. Display the data as unavailable, not zero; no substitute counts are returned.
• 409 with /usage-not-ready: Do not bill your customers for this period yet. Contact Dockt support to resolve missing or mismatched usage or finalize the statement.
• 400 with /invalid-billing-query: Fix the dates, limit, or cursor. Malformed parameters can also return a general validation error.
• 403 or 404: Check credential scope and Account ownership.

Billing-read failures do not prevent Assessment processing. Include the response’s x-request-id when contacting support.