Usage and billing
Understand what your organization consumes and how it is counted.
Free during the research preview
Periplus is free while the service is in research preview, with limited capacity and no uptime guarantee. Usage-based billing is planned after a stable production release. Pricing and billing terms will be published before charging begins. Current usage figures are consumption, not charges.
GET /access exposes this current policy in its billing field. Resource allowances and the organization challenge-resolution allowance (allow_challenge_resolution) are separate from customer billing; see MCP access and billing status.
Resource usage
Usage measures the resources your organization consumes.
| Category | Measurement |
|---|---|
| Pages captured | Distinct successful captures supplied to your organization, broken down by capture, crawl, or schedule; shared or reused captures count, failed attempts do not |
| Challenge resolution | Captured pages that needed paid bot-challenge resolution, counted only for captures, crawls and schedules that asked for it (resolve_bot_challenges); never counted again on reuse |
| Pinned capture-days | One pinned capture kept for 24 hours |
Pins accumulate with time
Ten captures pinned for three full days use 30 capture-days. Usage accrues as pinned time passes, not for the entire promised period upfront. The default seven days does not count toward pinned capture-days. Your pins do count, including any time within those first seven days.
Overlapping pins on the same capture count once in your organization’s total. Per-pin breakdowns can overlap and need not add up to the total. Other organizations’ acquisitions do not increase your pinned capture count.
10 captures × 3 days = 30 capture-days
Assumes every pinned capture is kept for the full period. Overlapping pins count once per capture and organization. This estimates usage, not a price.
Query activity is separate
Query activity identifies who ran SQL through the app, SDK, API, or a pin or schedule created from SQL, with available execution statistics. Detailed history is best-effort, retained for 30 days, and is not a billing ledger. Schema lookups and preparation are not query executions.
Read date ranges carefully
Usage uses UTC date ranges. Unavailable history is not zero usage. Resource names reflect when usage was recorded; renaming or deleting a pin, schedule, or request does not rewrite past usage. Pausing a schedule or deleting a pin changes future captures or protection, not the usage already accumulated.
Read consumption
Dates are UTC, and end is exclusive. Usage reports consumption, not a price or invoice. Omit dates for the current month.
Python
from periplus_sdk import Client
with Client() as client:
usage = client.usage.get()
print(usage.pages, usage.pinned_capture_days)cURL
curl --fail-with-body "${PERIPLUS_API_URL:-https://api.periplus.dev}/usage" \
-H "Authorization: Bearer $PERIPLUS_API_KEY"Page through query activity
History is best-effort and expires after 30 days. Follow next_cursor to read beyond the most recent 50 executions; get an execution to retrieve its SQL and parameters.
Python
from periplus_sdk import Client
with Client() as client:
for execution in client.query_history.iter():
print(execution.execution_id, execution.user_id, execution.outcome)cURL
curl --fail-with-body "${PERIPLUS_API_URL:-https://api.periplus.dev}/usage/query-history?limit=50" \
-H "Authorization: Bearer $PERIPLUS_API_KEY"