External API docs

Get credit balance

Read the remaining credit balance and the current billing period for your team.

Overview

Use this endpoint to monitor how many credits your team has left and when the current billing period ends. Credits are shared across all enrichment endpoints (search, find-people, lookup-people, lookup-business-email).

The response shape is the same for all plans, but the period window and balance come from different sources:

  • Subscription plans — balance is live from the credit ledger; period matches your active Stripe subscription window.
  • Trial keys — balance is 5000 - credits_used; period is the current calendar year.
  • Unlimited keys (e.g. Clay production) — balance is a fixed sentinel (10000), not the real cap; period is the current calendar year.

Before you start

Make sure you have:

  • an Openmart account
  • an API key
  • a tool to send API requests, such as Postman or curl

Authentication: send your key in the X-API-Key header. Authorization: Bearer <key> is also accepted. Missing or unknown keys return HTTP 401 with {"detail":"Invalid API Key"}.

1

Example: Read your credit balance

Endpoint
GET https://api.openmart.ai/api/v2/credit-balance

cURL request

cURL
curl --request GET \
  --url https://api.openmart.ai/api/v2/credit-balance \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <your_api_key>'

Response example

JSON
{
  "period_start": "2025-08-05T20:22:47Z",
  "period_end": "2026-08-05T20:22:47Z",
  "balance": 998931751
}

Key elements of the API response

Response element
period_start
Type
string (RFC3339 UTC)
Description
Start of the current billing window. For subscription keys, mirrors Stripe’s current_period_start. For trial and unlimited keys, fixed to January 1 (UTC) of the current year.
Response element
period_end
Type
string (RFC3339 UTC)
Description
End of the current billing window. Matches the source of period_start (Stripe or calendar-year).
Response element
balance
Type
integer
Description
Remaining credits in the current period. Unlimited-plan keys (e.g. Clay production) return a fixed sentinel of 10000 — it is not the real cap.

Request parameters

This endpoint takes no request body and no query parameters. The API key in your header determines which team's balance is returned.

# Get Credit Balance

## Endpoint

GET https://api.openmart.ai/api/v2/credit-balance

## Description

Returns the calling team's remaining Openmart credits and the current
billing period window.

## Authentication

- `X-API-Key: <your_api_key>` (recommended)
- `Authorization: Bearer <your_api_key>` (also accepted)

Missing or unknown keys return HTTP 401 with
`{"detail":"Invalid API Key"}`.

## Plan branches

- Subscription keys — live balance from the credit ledger; period
  mirrors the active Stripe subscription window.
- Trial keys — balance is `5000 - credits_used`; period is the current
  calendar year (UTC).
- Unlimited keys (e.g. Clay production) — balance is a fixed sentinel
  of `10000` (NOT the real cap); period is the current calendar year.

## Example Request

```bash
curl -X GET "https://api.openmart.ai/api/v2/credit-balance" \
  -H "Accept: application/json" \
  -H "X-API-Key: <your_api_key>"
```

## Example Response

```json
{
  "period_start": "2025-08-05T20:22:47Z",
  "period_end":   "2026-08-05T20:22:47Z",
  "balance":      998931751
}
```

## Errors

- 401 — missing or invalid API key (`{"detail":"Invalid API Key"}`)
- 500 — subscription lookup or balance calculation failed