Get Usage

GET /v1/usage

Get the current extraction usage for the authenticated user's billing period. Use this endpoint to monitor consumption and avoid hitting plan limits.

Try it

Test this endpoint interactively in the Swagger UI.

Authorization required

Include your API key in the Authorization header.

Request

Headers

Header	Value	Required
Authorization	Bearer <token>	Yes

This endpoint takes no query parameters or request body.

Code Examples

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345"

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/usage', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})

const { data } = await response.json()
console.log(`${data.usage} / ${data.limit} extractions used (${data.plan} plan)`)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.get(
    "https://api.docmap.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]
print(f"{data['usage']} / {data['limit']} extractions used ({data['plan']} plan)")

Response

Status: 200 OK

The response body is wrapped in a data object.

Fields

Field	Type	Description
plan	string	The user's current plan: free, starter, core, or pro.
usage	number	Number of extractions consumed in the current billing period.
limit	number	Maximum number of extractions allowed for the current plan.
periodKey	string	Current billing period in YYYY-MM format.

Example

{
  "data": {
    "plan": "starter",
    "usage": 142,
    "limit": 500,
    "periodKey": "2024-11"
  }
}

Errors

Status	Code	Description
401	UNAUTHORIZED	Missing, invalid, or expired API key / token.