API

Usage and quota

Plans belong to the institution account, not to a single journal. All journals of an institution share one yearly quota of accepted invitations.

What is counted

Searches are free and unlimited, apart from the rate limit.
One unit is an invitation a reviewer accepted. Declined, expired and cancelled invitations are not counted.
Beyond the included quota, each accepted invitation is billed as overage. Your work is never blocked by the quota itself.
If your institution sets an overage cap in the console, new invitations are refused once the cap is reached.

GET /v1/usage

Returns the quota of the institution account the key belongs to, for the current period.

Request

curl https://api.scholvet.com/v1/usage \
  -H "X-Api-Key: $SCHOLVET_API_KEY"

Response body

Field	Type	Description
`plan`	`string \| null`	Plan key; null before the account is activated.
`periodStart`	`date-time \| null`	Start of the current period.
`periodEnd`	`date-time \| null`	End of the current period (exclusive).
`included` required	`integer`	Accepted invitations included in the plan.
`used` required	`integer`	Accepted invitations in the period, all journals of the account.
`remaining` required	`integer`	Included invitations left.
`overage` required	`integer`	Accepted invitations beyond the quota, billed as overage.
`overageCap`	`integer \| null`	Ceiling on overage set by the institution; null for none.
`capReached` required	`boolean`	true when the cap is reached and new invitations are refused.
`usedByThisJournal` required	`integer`	Accepted invitations of the journal this key belongs to.
`credits` required	`integer`	Network credits granted in this period. They are added to included: remaining = included + credits − used.

Response

{
  "plan": "standard",
  "periodStart": "2026-01-01T00:00:00Z",
  "periodEnd": "2027-01-01T00:00:00Z",
  "included": 200,
  "used": 214,
  "remaining": 0,
  "overage": 8,
  "overageCap": 50,
  "capReached": false,
  "usedByThisJournal": 37,
  "credits": 6
}

Network credits

When a reviewer that one of your journals added (POST /v1/reviewers, or a reviewer suggested by the authors) accepts an invitation from a journal of another institution, your account receives one accepted invitation as credit, up to five per reviewer. Credits count in the period they are granted in and do not carry over. Inviting the reviewers you added yourself earns nothing.

When the cap is reached

Creating an invitation answers 402 with the code overage_cap_reached. Searches and everything else keep working. An owner can raise the cap in the console.

Response

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.3",
  "title": "Payment Required",
  "status": 402,
  "detail": "The overage cap your institution set for this period is reached. Raise it in the console or wait for the next period.",
  "code": "overage_cap_reached"
}

Next: Webhooks →