05 · API

Read your numbers over the REST API

The dashboard's own numbers, as JSON, for one site, with a key that can only read.

01Keys

Make keys on the site's Setup page, under API keys. A key (opa_ and 40 characters) is shown once: only a hash of it and its first characters are kept.
A key reads one site, the one it was made on. Revoking it works at once.
A key reads only, unless Record payments was ticked when it was made: then it can also post payments (Payments API).

Send the key on every request as Authorization: Bearer opa_…:

Shell

export TALLY_API_KEY=opa_…
curl -s -H "Authorization: Bearer $TALLY_API_KEY" "https://tallybyoutpost.com/api/v1/sites"

02Routes

All are GET, under https://tallybyoutpost.com/api/v1, and {id} is the site's id. Each takes the dashboard's parameters and gives the dashboard's own numbers:

Route	What it gives
`GET /sites`	The key's site: its id, name, domain, time zone and mode.
`GET /sites/{id}/overview`	The dashboard's numbers for a period and the one before: visitors, pageviews, visits, engaged time and revenue.
`GET /sites/{id}/timeseries`	The chart: visitors and pageviews per hour or day, with revenue when there are payments.
`GET /sites/{id}/breakdown/{dimension}`	Sources, channels, pages, countries, devices and the rest, with each row's revenue.
`GET /sites/{id}/sales`	Payments, newest first, each with how it was linked.
`GET /sites/{id}/receipts/{payment_id}`	One payment's receipt: the chain from first visit to payment.
`GET /sites/{id}/coverage`	The share of sales linked to a visitor, by method, and the fixes.
`GET /sites/{id}/visitors`	The visitor list, with each visitor's visits and what they paid.
`GET /sites/{id}/visitors/{visitor}`	One visitor's journey.
`GET /sites/{id}/goals`	Each goal completed, with its converting visitors and their revenue, and the funnels.
`GET /sites/{id}/funnels/{id}`	One funnel, step by step.
`GET /sites/{id}/realtime`	Who is on the site in the last five minutes, and the last hour's sales.
`GET /sites/{id}/peak-hours`	Visits, sales and revenue by weekday and local hour.
`GET /sites/{id}/pages`	How pages are read: views, reading time, scroll depth, entries and exits.
`GET /sites/{id}/path-to-purchase`	How buyers got there: time and visits before paying, and first-touch to credited source.
`GET /sites/{id}/ltv`	Lifetime value by the source that first brought each customer.

Sources by revenue, last 30 days

curl -s -H "Authorization: Bearer $TALLY_API_KEY" \
  "https://tallybyoutpost.com/api/v1/sites/k3xq2mfa7twp/breakdown/source?period=30d&sort=revenue"

03Parameters

Parameter	Values
`period`	`today`, `yesterday`, `7d`, `30d`, `12m`. Each route has a default.
`from`, `to`	A custom range, `YYYY-MM-DD`, both given, up to 366 days. Not with `period`.
`compare`	`off` (the default), `previous` or `year`.
`f.<dim>`	A filter: `f.country=DE`, `f.source=x.com`, `f.page=/pricing`, `f.device=mobile`, and the dashboard's other dimensions.
`limit`, `cursor`	Rows per page, and the `next_cursor` of the page before.

A parameter a route doesn't take is refused with 400, so a typo never passes for an answer.

04Answers

JSON, with money as integer cents and its currency: {"cents": 4900, "currency": "USD", "exponent": 2}. Totals are in US dollars; each sale also carries its amount as charged.
Times are RFC 3339 in UTC; days are cut in the site's time zone, which every range names.
Shares and rates are 0 to 1: 0.1234 is 12.34%.
Errors are {"error": {"code", "message"}}, where the message is a sentence you can show as it is: 400 invalid_parameter, 401 unauthorized, 402 payment_required (the account has no plan), 404 not_found, 429 rate_limited and 503 unavailable.

05Rate limits

Each key may make 120 requests a minute, REST and MCP together, refilled as it goes. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; past the limit, 429 with Retry-After in seconds.

06Check it worked

Something missing, or not what you see? Write to support@tallybyoutpost.com and say which page.