API Reporting

Sapling's API endpoints for retrieving API usage analytics.

API Usage POST

A self-serve endpoint for retrieving aggregate API usage, cost, and quota information for the account that owns the calling API key.

Usage is scoped to the account that owns the calling key:

For a team-scoped key, the response covers all of the team's active keys.
For a user key, the response covers all of that user's active keys.

The endpoint returns aggregates only. It does not return per-call rows and does not support pagination or limit/offset parameters. No request text or content hashes are stored in, or returned by, this endpoint.

Masked key IDs

API keys are never returned in raw form. In every section of the response, each key is identified by a stable, masked ID of the form ****<last4>-<hash8>, where <last4> is the last four characters of the key and <hash8> is the first eight hex characters of the SHA-256 hash of the key. The same key always maps to the same masked ID, and the ID is consistent across every section of the response (by_api_key, daily_usage, and monthly_usage).

Request Parameters

https://api.sapling.ai/api/v1/reporting/api_usage

HTTP method: POST

key: String
32-character API key. Can also be supplied as a ?key= query parameter or via the Authorization header as a bearer token. If multiple are provided, the key parameter takes precedence.

start_days_back: Optional Integer
Number of days back at which the reporting window starts (e.g. 7 starts the window one week ago). Defaults to the start of the current calendar month.

end_days_back: Optional Integer
Number of days back at which the reporting window ends. Defaults to 0 (today, inclusive).

Both start_days_back and end_days_back are validated as follows:

Each must be an integer, otherwise the endpoint returns HTTP 400.
Each must be non-negative, otherwise the endpoint returns HTTP 400.
start_days_back must be greater than or equal to end_days_back, otherwise the endpoint returns HTTP 400.
The resolved window may not exceed 1 year, otherwise the endpoint returns HTTP 403.

The window is also clamped to the age of the account, so it will never start before the account was created.

Sample Code

cURL
Python

curl -X POST https://api.sapling.ai/api/v1/reporting/api_usage \
     -H "Content-Type: application/json" \
     -d '{"key":"<api-key>", "start_days_back": 30, "end_days_back": 0}'

import requests
from pprint import pprint

try:
    response = requests.post(
        "https://api.sapling.ai/api/v1/reporting/api_usage",
        json={
            "key": "<api-key>",
            "start_days_back": 30,
            "end_days_back": 0,
        }
    )
    if 200 <= response.status_code < 300:
        pprint(response.json())
    else:
        print('Error: ', str(response.status_code), response.text)
except Exception as e:
    print('Error: ', e)

Response Parameters

JSON structure with aggregate usage, cost, and quota information for the resolved window.

start_date / end_date: String (ISO date)
Inclusive start and end dates of the resolved reporting window.

total_characters: Integer
Total characters processed across the account during the window.

total_cost_usd: Float
Cost of the usage in the window at list pricing, computed per (endpoint, month). See the Pricing page for list rates.

currency: String
Currency of total_cost_usd and by_endpoint[*].cost_usd (e.g. USD).

by_api_key: Object
Map keyed by masked key ID. Each value has the following fields:

api_key (String): The masked key ID, e.g. ****abcd-1a2b3c4d.
tag (String): The key's tag/label, if any.
characters (Integer): Characters processed by this key in the window.
monthly_limit (Integer): Monthly character limit (-1 means no limit).
monthly_usage (Integer): Characters used in the current calendar month.
remaining_quota (Integer or null): Remaining characters this month (null when there is no limit).
quota_exceeded (Boolean): Whether the monthly limit has been exceeded.

daily_usage: Object
Map of masked key ID to a { "YYYY-MM-DD": <int> } object giving characters processed per day.

monthly_usage: Object
Map of masked key ID to a { "YYYY-MM": <int> } object giving characters processed per calendar month.

by_endpoint: Object
Map of endpoint name (e.g. EDIT) to { "characters": <int>, "cost_usd": <float> }.

last_updated: String (ISO timestamp) or null
Timestamp of the most recent usage record in the window, or null if there is no usage in the window.

Sample Response

{
    "start_date": "2026-05-13",
    "end_date": "2026-06-12",
    "total_characters": 36000,
    "total_cost_usd": 0.9,
    "currency": "USD",
    "by_api_key": {
        "****abcd-1a2b3c4d": {
            "api_key": "****abcd-1a2b3c4d",
            "tag": "production",
            "characters": 20000,
            "monthly_limit": 1000000,
            "monthly_usage": 20000,
            "remaining_quota": 980000,
            "quota_exceeded": false
        },
        "****wxyz-9f8e7d6c": {
            "api_key": "****wxyz-9f8e7d6c",
            "tag": "staging",
            "characters": 16000,
            "monthly_limit": -1,
            "monthly_usage": 16000,
            "remaining_quota": null,
            "quota_exceeded": false
        }
    },
    "daily_usage": {
        "****abcd-1a2b3c4d": {
            "2026-06-10": 4000,
            "2026-06-11": 16000
        },
        "****wxyz-9f8e7d6c": {
            "2026-06-11": 16000
        }
    },
    "monthly_usage": {
        "****abcd-1a2b3c4d": {
            "2026-05": 0,
            "2026-06": 20000
        },
        "****wxyz-9f8e7d6c": {
            "2026-06": 16000
        }
    },
    "by_endpoint": {
        "EDIT": {
            "characters": 20000,
            "cost_usd": 0.5
        },
        "SPELLCHECK": {
            "characters": 16000,
            "cost_usd": 0.4
        }
    },
    "last_updated": "2026-06-11T17:06:15.416190"
}

API Quota Usage POST

This endpoint allows users to get API usage for a given time period as well as check their current quota.

Request Parameters

https://api.sapling.ai/api/v1/reporting/api_quota_usage

HTTP method: POST

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

start_days_back: Integer
Starting number of days ago (7 would consider usage starting 1 week ago).

end_days_back: Integer
Ending number of days ago (0 would mean up until current date).

Response Parameters

JSON structure with API usage reporting information. There may be additional metadata that is subject to change.

{
    "quota": <int>,             // Quota allocated to API key per month
    "usage": <int>,             // Usage volume during time period
    "last_updated": <float>,    // Timestamp that usage information was last updated (Unix epoch seconds)
}

API Endpoint Usage

This endpoint allows users to get API usage for each endpoint over a given time period.

Request Parameters

https://api.sapling.ai/api/v1/reporting/api_endpoint_usage

HTTP method: POST

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

start_days_back: Integer
Starting number of days ago (7 would consider usage starting 1 week ago).

end_days_back: Integer
Ending number of days ago (0 would mean up until current date).

interval: String
Interval to report usage by. Can be Daily, Weekly, or Monthly.

Response Parameters

JSON structure with API endpoint usage reporting information. For each endpoint, e.g. EDIT or SPELLCHECK, the usage is reported for each interval range in the time period.

{
    "data": {
        "<endpoint_name>": {
            "<day_number>": <int>,
            ...
        }
    },
    "last_updated": "<ISO timestamp>"
}

Example:

{
    "data": {
        "EDIT": {
            "0": 0,
            "1": 16000,
            "2": 0,
            "3": 0,
        },
        "SPELLCHECK": {
            "0": 0,
            "1": 0,
            "2": 20000,
            "3": 0,
        }
    },
    "last_updated": "2025-03-14T17:06:15.416190"
}

API User Activity

This endpoint allows users to get recorded user actions over a given time period. The current actions recorded are:

Edits shown
Edits accepted
Edits ignored Please note these require that the accept and reject API endpoints have been used.

The endpoint also returns active users.

Request Parameters

https://api.sapling.ai/api/v1/reporting/api_user_activity

HTTP method: POST

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

start_days_back: Integer
Starting number of days ago (7 would consider usage starting 1 week ago).

end_days_back: Integer
Ending number of days ago (0 would mean up until current date).

Response Parameters

JSON structure with activity reporting information.

{
    "edits_shown": <int>,
    "edits_accepted": <int>,
    "edits_ignored": <int>,
    "active_users": {
        "logged_in": <int>,
        "anonymous": <int>
    }
}

API Usage POST​

Request Parameters​

Sample Code​

Response Parameters​

Sample Response​

API Quota Usage POST​

Request Parameters​

Response Parameters​

API Endpoint Usage​

Request Parameters​

Response Parameters​

API User Activity​

Request Parameters​

Response Parameters​

API Usage POST

Request Parameters

Sample Code

Response Parameters

Sample Response

API Quota Usage POST

Request Parameters

Response Parameters

API Endpoint Usage

Request Parameters

Response Parameters

API User Activity

Request Parameters

Response Parameters