Installgraph

Start free

Your balance and recent usage

GET/v1/usage

Returns your key's credit balance, rate limit, prices and the last 30 days of usage, free.

View as MarkdownOpenAPI specAll docs for LLMs

Check it before a large pull, or to reconcile what a job spent.

Free, and needs no scope.

Request

curl "https://api.installgraph.com/v1/usage" \
  -H "Authorization: Bearer $INSTALLGRAPH_API_KEY"

Response

200. The example's stores are fictional.

{
  "data": {
    "key": {
      "prefix": "sfs_01234567",
      "owner": "you@company.com",
      "name": "Default",
      "scopes": [
        "companies:read",
        "apps:read",
        "events:read"
      ]
    },
    "credits": {
      "balance": 46,
      "unlimited": false
    },
    "rateLimit": {
      "perMinute": 60,
      "remaining": 59,
      "resetAt": "2026-11-06T10:15:00.000Z"
    },
    "prices": {
      "GET /v1/companies/{domain}": {
        "perRequest": 1
      },
      "GET /v1/apps/{slug}/companies": {
        "perRow": 1
      }
    },
    "last30Days": {
      "since": "2026-10-07T10:14:12.000Z",
      "requests": 3,
      "credits": 4,
      "byEndpoint": [
        {
          "endpoint": "GET /v1/apps/{slug}/companies",
          "requests": 1,
          "rows": 2,
          "credits": 2
        },
        {
          "endpoint": "GET /v1/companies/{domain}",
          "requests": 1,
          "rows": 1,
          "credits": 1
        },
        {
          "endpoint": "GET /v1/events",
          "requests": 1,
          "rows": 1,
          "credits": 1
        }
      ]
    },
    "recent": [
      {
        "at": "2026-11-06T10:14:02.000Z",
        "type": "usage",
        "amount": -1,
        "credits": 1,
        "balanceAfter": 46,
        "endpoint": "GET /v1/events",
        "rows": 1,
        "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
        "note": null
      },
      {
        "at": "2026-11-05T16:20:41.000Z",
        "type": "grant",
        "amount": 25,
        "credits": 25,
        "balanceAfter": 50,
        "endpoint": null,
        "rows": null,
        "requestId": null,
        "note": "Verified email"
      }
    ]
  },
  "meta": {
    "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
    "creditsUsed": 0,
    "creditsCharged": 0,
    "creditsRemaining": 46,
    "freeRepulls": 0
  }
}

Fields

Field Type Description
data.key object
data.key.prefix string Example: sfs_Ab12Cd34.
data.key.owner string
data.key.name string | null
data.key.scopes string[] One of companies:read, apps:read, events:read.
data.credits object
data.credits.balance integer | null Null for unlimited keys.
data.credits.unlimited boolean
data.rateLimit object
data.rateLimit.perMinute integer
data.rateLimit.remaining integer
data.rateLimit.resetAt string (date-time)
data.prices object Credits per endpoint, { perRequest } or { perRow }.
data.last30Days object
data.last30Days.since string (date-time)
data.last30Days.requests integer Billed requests (free ones are not recorded).
data.last30Days.credits integer
data.last30Days.byEndpoint object[]
data.last30Days.byEndpoint[].endpoint string
data.last30Days.byEndpoint[].requests integer
data.last30Days.byEndpoint[].rows integer
data.last30Days.byEndpoint[].credits integer
data.recent object[] The latest 50 ledger entries, newest first.
data.recent[].at string (date-time)
data.recent[].type string One of usage, grant, purchase, refund, adjustment.
data.recent[].amount integer Change to the balance.
data.recent[].credits integer
data.recent[].balanceAfter integer | null
data.recent[].endpoint string | null
data.recent[].rows integer | null
data.recent[].requestId string | null
data.recent[].note string | null

Every keyed response also carries meta (requestId, creditsUsed, creditsRemaining, freeRepulls) and the X-Credits-* and X-RateLimit-* headers. See Credits and Rate limits.

Errors

Status Code Meaning What to do
401 missing_api_key No key was sent. Send Authorization: Bearer sfs_… or X-API-Key: sfs_….
401 invalid_api_key The key is not one we issued. Check for truncation or whitespace; keys are sfs_ plus 32 letters and digits.
401 api_key_revoked The key was revoked. Make a new key at installgraph.com/account.
403 insufficient_scope The key lacks this endpoint's scope. Use a key with the scope the endpoint lists (GET /v1/usage shows yours).
403 api_key_suspended The key is suspended. Talk to us, quoting requestId.
429 rate_limited Too many requests this minute. Wait Retry-After seconds, then retry.

All codes: Errors.