Skip to main content
Track per-tenant credit consumption and API usage to understand how each tenant utilizes your Papermap integration. This feature enables transparent billing, usage analytics, and resource monitoring.

​
Overview

When using API key authentication with the X-Tenant-ID header, Papermap automatically tracks:
  • Credits consumed per tenant per billing period
  • Request count per tenant per billing period
  • Monthly aggregation with automatic period bucketing
This allows workspace owners to see which tenants are consuming credits and resources.

​
How It Works

API Request with X-Tenant-ID header
    ↓
Papermap processes request
    ↓
Credits consumed from workspace quota
    ↓
Usage attributed to tenant (monthly bucket)
    ↓
Query usage via API endpoints

​
Billing Period

Usage is automatically bucketed by calendar month:
  • Period Start: First day of month (e.g., 2025-01-01 00:00:00)
  • Period End: Last day of month (e.g., 2025-01-31 23:59:59)
Each unique tenant gets a separate usage record per month.

​
API Endpoints

The base URL for the Papermap API is https://prod.dataapi.papermap.ai/.

​
Get Workspace Tenant Usage

Retrieve usage data for all tenants in a workspace. Request: 
GET /api/v1/external/workspaces/{workspace_id}/tenant-usage
Authorization: <HMAC Signature Headers>
Query Parameters:
ParameterTypeRequiredDescription
from_periodstringNoStart period filter (YYYY-MM format)
to_periodstringNoEnd period filter (YYYY-MM format)
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page (default: 50, max: 100)
Example Request: 
curl -X GET "${PAPERMAP_API_URL}/api/v1/external/workspaces/ws-123/tenant-usage?from_period=2025-01&to_period=2025-12&page=1&per_page=20" \
  -H "X-API-Key-ID: your-api-key-id" \
  -H "X-Workspace-ID: ws-123" \
  -H "X-Valid-Until: 1735689600" \
  -H "X-Signature: <hmac-signature>"
Response: 
{
  "success": true,
  "message": "Tenant usage retrieved successfully",
  "data": {
    "workspace_id": "ws-123",
    "usage": [
      {
        "tenant_id": "tenant-abc",
        "period": "2025-01",
        "period_start": "2025-01-01T00:00:00",
        "period_end": "2025-01-31T23:59:59",
        "credits_used": 1500,
        "request_count": 450
      },
      {
        "tenant_id": "tenant-xyz",
        "period": "2025-01",
        "period_start": "2025-01-01T00:00:00",
        "period_end": "2025-01-31T23:59:59",
        "credits_used": 800,
        "request_count": 200
      }
    ],
    "total_records": 2,
    "total_pages": 1
  }
}

​
Get Tenant Usage History

Retrieve usage history for a specific tenant. Request: 
GET /api/v1/external/workspaces/{workspace_id}/tenant-usage/{tenant_id}
Authorization: <HMAC Signature Headers>
Query Parameters:
ParameterTypeRequiredDescription
from_periodstringNoStart period filter (YYYY-MM format)
to_periodstringNoEnd period filter (YYYY-MM format)
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page (default: 50, max: 100)
Example Request: 
curl -X GET "${PAPERMAP_API_URL}/api/v1/external/workspaces/ws-123/tenant-usage/tenant-abc?from_period=2024-06&to_period=2025-01" \
  -H "X-API-Key-ID: your-api-key-id" \
  -H "X-Workspace-ID: ws-123" \
  -H "X-Valid-Until: 1735689600" \
  -H "X-Signature: <hmac-signature>"
Response: 
{
  "success": true,
  "message": "Tenant usage history retrieved successfully",
  "data": {
    "workspace_id": "ws-123",
    "tenant_id": "tenant-abc",
    "usage": [
      {
        "tenant_id": "tenant-abc",
        "period": "2024-12",
        "period_start": "2024-12-01T00:00:00",
        "period_end": "2024-12-31T23:59:59",
        "credits_used": 2100,
        "request_count": 630
      },
      {
        "tenant_id": "tenant-abc",
        "period": "2025-01",
        "period_start": "2025-01-01T00:00:00",
        "period_end": "2025-01-31T23:59:59",
        "credits_used": 1500,
        "request_count": 450
      }
    ],
    "total_records": 2,
    "total_pages": 1
  }
}

​
Authentication

These endpoints use the same HMAC signature authentication as other external API endpoints. See the Authentication Guide for details. Required headers:
  • X-API-Key-ID: Your API key identifier
  • X-Workspace-ID: Your workspace ID
  • X-Valid-Until: Unix timestamp for request expiration
  • X-Signature: HMAC-SHA256 signature

​
Implementation Examples

The _get_auth_headers function is a helper function that generates the HMAC signature for the API request found in the HMAC Authentication guide.
import httpx
from typing import Optional

async def get_tenant_usage(
    workspace_id: str,
    from_period: Optional[str] = None,
    to_period: Optional[str] = None,
    page: int = 1,
    per_page: int = 50
):
    headers = _get_auth_headers(workspace_id, API_KEY_ID, SECRET_KEY)

    params = {"page": page, "per_page": per_page}
    if from_period:
        params["from_period"] = from_period
    if to_period:
        params["to_period"] = to_period

    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"{PAPERMAP_API_URL}/api/v1/external/workspaces/{workspace_id}/tenant-usage",
            headers=headers,
            params=params
        )

    return response.json()

# Example usage
usage = await get_tenant_usage("ws-123", from_period="2025-01", to_period="2025-12")
for item in usage["data"]["usage"]:
    print(f"Tenant {item['tenant_id']}: {item['credits_used']} credits")

​
Use Cases

Billing & Invoicing

Generate per-tenant invoices based on actual usage
  • Query usage for billing period
  • Calculate costs based on credits consumed
  • Automate invoice generation

Usage Analytics

Monitor tenant consumption patterns
  • Identify high-usage tenants
  • Track usage trends over time
  • Plan capacity accordingly

Quota Management

Implement tenant-level quotas
  • Compare usage against limits
  • Send usage warnings
  • Enforce rate limits per tenant

Cost Allocation

Attribute costs to business units
  • Track departmental usage
  • Chargeback reporting
  • Budget planning

​
Response Fields

FieldTypeDescription
tenant_idstringThe tenant identifier from X-Tenant-ID header
periodstringBilling period in YYYY-MM format
period_startdatetimeStart of the billing period
period_enddatetimeEnd of the billing period
credits_usedintegerTotal credits consumed in this period
request_countintegerTotal API requests made in this period
total_recordsintegerTotal number of usage records (for pagination)
total_pagesintegerTotal number of pages available

​
Error Responses

StatusErrorDescription
400Invalid period formatPeriod must be in YYYY-MM format
401UnauthorizedInvalid or missing authentication
403Access deniedNo access to the specified workspace
404Not foundWorkspace or tenant not found
Example Error Response: 
{
  "success": false,
  "message": "Invalid from_period format. Use YYYY-MM",
  "data": null
}

​
Next Steps

Authentication

Learn how to authenticate API requests

API Endpoints

Explore other available API endpoints