Mathpix

Mathpix OCR Usage API

Query OCR consumption metrics aggregated by usage_type, request_args_hash, or app_id, over arbitrary timespans (hour, day, week, month). Used to track consumption trends and reconcile billing.

Mathpix OCR Usage API is one of 7 APIs that Mathpix publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Usage, Metering, FinOps, and Administration. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.mathpix.com/reference/ocr-usage

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/mathpix/refs/heads/main/openapi/mathpix-ocr-usage-api-openapi.yml

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/mathpix/refs/heads/main/capabilities/ocr-usage-usage.yaml

OpenAPI Specification

mathpix-ocr-usage-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Mathpix OCR Usage API
  description: >
    Query OCR consumption metrics aggregated by usage type, request signature, or application,
    over arbitrary timespans. Used to track consumption trends and reconcile billing.
  version: v3
  contact:
    name: Mathpix Support
    url: https://docs.mathpix.com
    email: [email protected]
  license:
    name: Mathpix Terms of Service
    url: https://mathpix.com/terms-of-service
servers:
  - url: https://api.mathpix.com
    description: Production Server
security:
  - AppIdAuth: []
    AppKeyAuth: []
tags:
  - name: Usage
    description: Inspect OCR consumption.
paths:
  /v3/ocr-usage:
    get:
      summary: Query OCR Usage
      description: Aggregate OCR usage across a time window. Group by usage_type, request_args_hash, or app_id, and pick a timespan such as month, week, day, or hour.
      operationId: queryOcrUsage
      tags:
        - Usage
      parameters:
        - $ref: '#/components/parameters/AppIdHeader'
        - $ref: '#/components/parameters/AppKeyHeader'
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: ISO datetime lower bound (inclusive).
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: ISO datetime upper bound (exclusive).
        - name: group_by
          in: query
          required: true
          schema:
            type: string
            enum: [usage_type, request_args_hash, app_id]
        - name: timespan
          in: query
          required: true
          schema:
            type: string
            enum: [hour, day, week, month]
      responses:
        '200':
          description: Aggregated usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrUsageResponse'
components:
  securitySchemes:
    AppIdAuth:
      type: apiKey
      in: header
      name: app_id
    AppKeyAuth:
      type: apiKey
      in: header
      name: app_key
  parameters:
    AppIdHeader:
      name: app_id
      in: header
      required: true
      schema:
        type: string
    AppKeyHeader:
      name: app_key
      in: header
      required: true
      schema:
        type: string
  schemas:
    UsageRecord:
      type: object
      properties:
        from_date:
          type: string
          format: date-time
        app_id:
          type: string
        group_id:
          type: string
        usage_type:
          type: string
          description: Service type (e.g. image, image-async, pdf, strokes, conversion).
        request_args_hash:
          type: string
        count:
          type: integer
    OcrUsageResponse:
      type: object
      properties:
        ocr_usage:
          type: array
          items:
            $ref: '#/components/schemas/UsageRecord'