Query OCR Usage

Track API usage over time, grouped by usage type, request args, or app ID.

GET v3/ocr-usage

GET api.mathpix.com/v3/ocr-usage

Returns aggregated API usage records for your app, grouped by usage type, request arguments hash, or app ID over a specified time range. Use this to track consumption trends and reconcile billing.

Example

cURL

# Example: Query API usage grouped by usage type for a date range
curl -X GET \
  'https://api.mathpix.com/v3/ocr-usage?from_date=2021-01-01T00%3A00%3A00.000Z&to_date=2021-01-02T00%3A00%3A00.000Z&group_by=usage_type&timespan=month' \
  -H 'app_id: APP_ID' \
  -H 'app_key: APP_KEY'

Python

# Example: Query API usage grouped by usage type for a date range
import requests
url = "https://api.mathpix.com/v3/ocr-usage"
headers = {
    "app_id": "APP_ID",
    "app_key": "APP_KEY",
}
params = {
    "from_date": "2021-01-01T00:00:00.000Z",
    "to_date": "2021-01-02T00:00:00.000Z",
    "group_by": "usage_type",
    "timespan": "month",
}
response = requests.get(url, headers=headers, params=params, timeout=30)
print(response.json())

JavaScript / TypeScript

// Example: Query API usage grouped by usage type for a date range
const params = new URLSearchParams({
  from_date: "2021-01-01T00:00:00.000Z",
  to_date: "2021-01-02T00:00:00.000Z",
  group_by: "usage_type",
  timespan: "month",
});
const response = await fetch(
  `https://api.mathpix.com/v3/ocr-usage?${params}`,
  {
    headers: {
      app_id: "APP_ID",
      app_key: "APP_KEY",
    },
  }
);
const result = await response.json();
console.log(JSON.stringify(result, null, 2));

Go

// Example: Query API usage grouped by usage type for a date range
req, _ := http.NewRequest("GET",
    "https://api.mathpix.com/v3/ocr-usage?from_date=2021-01-01T00%3A00%3A00.000Z&to_date=2021-01-02T00%3A00%3A00.000Z&group_by=usage_type&timespan=month",
    nil)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result))

Java

// Example: Query API usage grouped by usage type for a date range
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/ocr-usage?from_date=2021-01-01T00%3A00%3A00.000Z&to_date=2021-01-02T00%3A00%3A00.000Z&group_by=usage_type&timespan=month"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Example response

{
  "ocr_usage": [
    {
      "from_date": "2022-01-01T00:00:00.000Z",
      "app_id": "mathpix",
      "group_id": "mathpix-group",
      "usage_type": "image",
      "request_args_hash": "1f241a3777a5646b98eb4e07c1e39f27770c14d8",
      "count": 21
    },
    {
      "from_date": "2022-01-01T00:00:00.000Z",
      "app_id": "mathpix",
      "group_id": "mathpix-group",
      "usage_type": "image-async",
      "request_args_hash": "",
      "count": 7
    }
  ]
}

Request Parameters

from_date string (optional)

starting (included) ISO datetime

to_date string (optional)

ending (excluded) ISO datetime

group_by string

return values aggregated by this parameter. One of usage_type, request_args_hash, app_id

timespan string

return aggregated by specified timespan

Response Body

ocr_usage UsageRecord[]

List of UsageRecord objects, one per time period and grouping

Type definitions

UsageRecord object

from_date string

starting (included) ISO datetime

app_id string

App ID associated with this usage record

group_id string (optional)

Group ID associated with the app

usage_type string

service kind (e.g. image, image-async)

request_args_hash string

Hash of the request arguments for this usage record

count number

number of requests according to the selected group_by request parameter