Extractor Usage

Monitor your API usage and check remaining extraction capacity. This endpoint helps you track your current usage limits and plan your data extraction workflows accordingly.

GET /extractor-usage

Overview

The Extractor Usage endpoint provides real-time information about your remaining API quota. Use this to monitor consumption, implement usage-based logic in your applications, and ensure smooth operation within your plan limits.

Usage Tracking

Your usage quota is measured in "pages processed" rather than individual API calls. A multi-page document counts as multiple page units.

Request Details

Method: GET Rate Limit: 5 requests per 5 seconds

Headers

Header	Value	Required	Description
Authorization	Bearer YOUR_API_KEY	✅	Your API authentication token

Query Parameters

Parameter	Type	Required	Description
start_date	string	❌	Start of date range in ISO 8601 format (e.g. 2024-01-01T00:00:00Z). When provided, pagesUsed is returned.
end_date	string	❌	End of date range in ISO 8601 format (e.g. 2024-12-31T23:59:59Z). Defaults to the current time if omitted.
by_user	boolean	❌	Set to true to break down workspace usage by individual user. Requires start_date to be set.

Examples

JavaScript

const baseUrl = 'https://sheets.lido.app/api/v1/extractor-usage';
const headers = { Authorization: 'Bearer YOUR_API_KEY' };

// Basic usage check
async function checkUsage() {
  const response = await fetch(baseUrl, { method: 'GET', headers });
  const data = await response.json();
  console.log(`Pages remaining: ${data.pagesRemaining}`);
  return data;
}

// Usage within a date range
async function checkUsageInRange() {
  const url = `${baseUrl}?start_date=2024-01-01T00:00:00Z&end_date=2024-12-31T23:59:59Z`;
  const response = await fetch(url, { method: 'GET', headers });
  const data = await response.json();
  console.log(`Pages remaining: ${data.pagesRemaining}`);
  console.log(`Pages used in range: ${data.pagesUsed}`);
  return data;
}

// Per-user breakdown for a workspace
async function checkUsageByUser() {
  const url = `${baseUrl}?start_date=2024-01-01T00:00:00Z&by_user=true`;
  const response = await fetch(url, { method: 'GET', headers });
  const data = await response.json();
  data.usageByUser.forEach(u => {
    console.log(`${u.email}: ${u.pagesUsed} pages used`);
  });
  return data;
}

Python

import requests

BASE_URL = "https://sheets.lido.app/api/v1/extractor-usage"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Basic usage check
def check_usage():
    response = requests.get(BASE_URL, headers=HEADERS)
    data = response.json()
    print(f"Pages remaining: {data['pagesRemaining']}")
    return data

# Usage within a date range
def check_usage_in_range():
    params = {
        "start_date": "2024-01-01T00:00:00Z",
        "end_date": "2024-12-31T23:59:59Z",
    }
    response = requests.get(BASE_URL, headers=HEADERS, params=params)
    data = response.json()
    print(f"Pages remaining: {data['pagesRemaining']}")
    print(f"Pages used in range: {data['pagesUsed']}")
    return data

# Per-user breakdown for a workspace
def check_usage_by_user():
    params = {
        "start_date": "2024-01-01T00:00:00Z",
        "by_user": "true",
    }
    response = requests.get(BASE_URL, headers=HEADERS, params=params)
    data = response.json()
    for user in data["usageByUser"]:
        print(f"{user['email']}: {user['pagesUsed']} pages used")
    return data

cURL

# Basic usage check
curl --request GET \
  --url 'https://sheets.lido.app/api/v1/extractor-usage' \
  --header 'Authorization: Bearer YOUR_API_KEY'

# Usage within a date range
curl --request GET \
  --url 'https://sheets.lido.app/api/v1/extractor-usage?start_date=2024-01-01T00%3A00%3A00Z&end_date=2024-12-31T23%3A59%3A59Z' \
  --header 'Authorization: Bearer YOUR_API_KEY'

# Per-user breakdown for a workspace
curl --request GET \
  --url 'https://sheets.lido.app/api/v1/extractor-usage?start_date=2024-01-01T00%3A00%3A00Z&by_user=true' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response

Default response (no date range)

{
  "pagesRemaining": 247
}

With start_date (and optional end_date)

{
  "pagesRemaining": 247,
  "pagesUsed": 53
}

With start_date and by_user=true

{
  "pagesRemaining": 247,
  "usageByUser": [
    {
      "userId": "user_abc123",
      "email": "alice@example.com",
      "pagesUsed": 30
    },
    {
      "userId": "user_def456",
      "email": "bob@example.com",
      "pagesUsed": 23
    }
  ]
}

Response Fields

Field	Type	Description
pagesRemaining	number	Number of document pages you can still process with your current plan
pagesUsed	number	Pages processed within the requested date range (present when start_date is provided and by_user is not true)
usageByUser	array	Per-user breakdown (present when by_user=true and start_date is provided)
usageByUser[].userId	string	Unique identifier of the workspace user
usageByUser[].email	string	Email address of the workspace user
usageByUser[].pagesUsed	number	Pages processed by this user within the requested date range

Usage Calculation

How Pages Are Counted

Your API usage is measured in processed pages, not individual API calls:

• Single-page document = 1 page unit
• 5-page PDF = 5 page units
• Image file = 1 page unit

Important notes:

• Failed extractions don't count - If a job fails due to processing errors, no pages are deducted from your quota
• Only pages in range are counted - When using pageRange, only the specified pages count toward usage
• Pages excluded by @exclude_pages do count - If you use @exclude_pages in your instructions to skip certain pages during processing, those pages still count toward your usage quota

Page Range Processing

When you specify a pageRange parameter:

// This processes only pages 2-4 (3 pages total)
{
  pageRange: "2-4",
  // ... other parameters
}
// Usage: 3 page units

// This processes the entire 10-page document
{
  pageRange: "", // or omit the parameter
  // ... other parameters
}
// Usage: 10 page units