Stats API

Get signups

Read confirmed signup totals, time series, the signup funnel, and source reports for your website.

Request

GET/api/v1/stats/signups

Call this endpoint from your server with a website-scoped Stats API bearer key. Follow Get started to create a key. The key selects your website; do not send a website ID.

request.sh

curl 'https://talvess.vercel.app/api/v1/stats/signups?days=7' \
  -H "Authorization: Bearer $TALVESS_STATS_KEY"

Query parameters

Parameter	Accepted values
`days`	1, 7, 30, or 90. Defaults to 30. Use this or a pair of explicit dates.
`startDate`	Inclusive UTC date in YYYY-MM-DD format. Requires endDate.
`endDate`	Inclusive UTC date in YYYY-MM-DD format. Requires startDate.
`interval`	hourly or daily. Defaults to hourly for days=1, otherwise daily.

Explicit ranges cover up to 365 days through today. Hourly ranges cover at most seven days. Do not combine days with explicit dates. Unknown or repeated parameters return 400 INVALID_QUERY.

Response

A successful response contains data with the report and meta.generatedAt and meta.expiresAt with its cache timestamps. The report contains these fields:

period: The reporting interval, UTC boundaries, and calculation time.
signups, previousSignups: Confirmed signup totals for the selected and previous period.
series, previousSeries: Signup totals over time for both periods.
signupRate, funnel: The existing signup rate and built-in signup funnel.
aiSignups, sources: Detected AI referral signups and up to 50 aggregate source rows. Direct or unknown sources remain separate.

Matching reports are cached for 900 seconds. Each key allows 60 requests per minute, including cache hits. Read the shared freshness and limits and errors and retries before integrating. An empty report is a successful response; a failed calculation returns an error.