Rate Limits & Usage

Monthly Extraction Limits

Each plan includes a fixed number of extractions per calendar month. Usage resets on the first day of each month (UTC).

Plan	Monthly Extractions	Price
Free	25	$0
Starter	350	-
Core	2,500	-
Pro	10,000	-

TIP

See docmap.io/#pricing for current plan pricing and feature comparison.

Checking Your Usage

Query the /v1/usage endpoint to see your current plan, usage count, and limit for the active billing period:

curl

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

TypeScript

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

const { data } = await response.json();

console.log(`Plan: ${data.plan}`);
console.log(`Usage: ${data.usage} / ${data.limit}`);
console.log(`Period: ${data.periodKey}`);

Python

import requests

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

data = response.json()["data"]

print(f"Plan: {data['plan']}")
print(f"Usage: {data['usage']} / {data['limit']}")
print(f"Period: {data['periodKey']}")

Example response:

{
  "data": {
    "plan": "core",
    "usage": 1847,
    "limit": 2500,
    "periodKey": "2025-07"
  }
}

Field	Description
plan	Your current plan: free, starter, core, or pro
usage	Number of extractions used in the current billing period
limit	Maximum extractions allowed for your plan
periodKey	Current billing period in YYYY-MM format

Handling Limit Exceeded

When your monthly limit is reached, any call to POST /v1/extractions/run returns a 429 status with the USAGE_LIMIT_EXCEEDED error code:

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly extraction limit reached (25/25). Upgrade your plan for more extractions."
  }
}

You have two options:

1. Upgrade your plan. Go to Settings > Billing in the DocMap dashboard. Your new limit takes effect immediately.
2. Wait for the next billing period. Usage resets automatically on the first of each month (UTC).

WARNING

Do not retry 429 USAGE_LIMIT_EXCEEDED errors. Unlike server errors, these will not resolve on their own. Check the /v1/usage endpoint to see your current count and limit before making batch requests.

Here is how to handle this gracefully in your code:

async function runExtraction(templateId: string, fileName: string, pdfBase64: string) {
  const response = await fetch("https://api.docmap.io/v1/extractions/run", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ templateId, fileName, pdfBase64, mimeType: "application/pdf" }),
  });

  if (response.status === 429) {
    const { error } = await response.json();
    if (error.code === "USAGE_LIMIT_EXCEEDED") {
      console.error("Monthly extraction limit reached. Upgrade your plan or wait until next month.");
      // Optionally check current usage
      const usageResponse = await fetch("https://api.docmap.io/v1/usage", {
        headers: { Authorization: `Bearer ${apiKey}` },
      });
      const { data: usage } = await usageResponse.json();
      console.log(`Current usage: ${usage.usage}/${usage.limit} (${usage.plan} plan)`);
      return null;
    }
  }

  const { data } = await response.json();
  return data;
}

Usage Warnings

DocMap automatically sends an email notification when your usage reaches 80% of your monthly limit. This gives you time to upgrade your plan before extractions are paused.

• The warning is sent once per billing period -- you will not receive repeated emails
• The email includes your current usage count, limit, and a direct link to upgrade
• Only the account owner receives usage warning emails

TIP

Monitor your usage programmatically by calling GET /v1/usage before starting large batch operations. This lets you check whether you have enough remaining capacity.

Request Rate Limits

In addition to monthly extraction limits, excessive request rates may be throttled to protect service stability. To avoid throttling:

• Add delays between batch requests. When processing many files, add a small delay (e.g. 200--500ms) between consecutive API calls instead of firing them all simultaneously.
• Use concurrency limits. If processing files in parallel, limit concurrency to 5--10 simultaneous requests.
• Monitor response times. If response times increase significantly, reduce your request rate.

// Process files with controlled concurrency
async function processFilesWithLimit(files: string[], concurrency = 5) {
  const results = [];

  for (let i = 0; i < files.length; i += concurrency) {
    const batch = files.slice(i, i + concurrency);

    const batchResults = await Promise.all(
      batch.map((file) => runExtraction("tmpl_abc123", file, encode(file)))
    );

    results.push(...batchResults);

    // Brief pause between batches
    if (i + concurrency < files.length) {
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  return results;
}