Usage

Credit balance and consumption, broken down by day, endpoint, and key. Free to call.

Endpoints

Method	Path	Scope	Credits	Description
GET	`/v1/usage`	`usage:read`	0	Consumption report

Parameters

Parameter	Type	Required	Description
`start_date`	date	no	Inclusive; defaults to the start of the current billing period
`end_date`	date	no	Inclusive; defaults to today
`group_by`	enum[]	no	Any of `date`, `endpoint`, `api_key`. Omit for totals only

Response

json

{
  "object": "usage",
  "period": { "start_date": "2026-08-01", "end_date": "2026-08-10" },
  "credits": { "granted": 10000, "consumed": 3140, "remaining": 6860,
               "renews_at": "2026-09-01T00:00:00Z" },
  "breakdown": [
    { "date": "2026-08-09", "endpoint": "searches", "api_key": "key_ak91ndu3fs",
      "requests": 412, "credits": 2060 },
    { "date": "2026-08-09", "endpoint": "chats.messages", "api_key": "key_ak91ndu3fs",
      "requests": 540, "credits": 1080 }
  ]
}

granted includes plan credits plus any top-ups. Unused credits do not roll over.

Retrieve usage by key

cURL

curl -G https://api.scispace.com/v1/usage \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  --data-urlencode "start_date=2026-08-01" \
  --data-urlencode "group_by[]=api_key" \
  --data-urlencode "group_by[]=endpoint"

Reconciliation

X-Credits-Cost on each response is authoritative in real time; /v1/usage is the daily record and may lag live traffic by up to 5 minutes. Reconcile daily, not per request.

Errors

Status	`code`	When
400	`parameter_invalid`	`start_date` after `end_date`, or a window over 365 days
403	`scope_missing`	key lacks `usage:read`

credit · pricing-and-credits · cost-control · api-keys

Last updated 2026-08-10