Use the Analytics API
Read your first report and reuse Hardal analytics in scripts and integrations.
Use the Analytics API to retrieve existing Hardal reports for your own dashboards, scheduled reporting scripts, or analysis workflows. Access is read-only and limited to the tenants approved for the credential.
To collect new data, use Send Events or Send Agent Events. An Analytics API key is not a collection credential.
1. Create an API key
Follow Get an API Key. Select only the tenants your integration needs and save the key in a server-side secret or environment variable.
Do not put the key in browser JavaScript, mobile code, URLs, or public repositories.
2. Find your tenant and source
Open Workspace Access. In Try it, paste the key into Bearer Token without a second Bearer prefix and send the request.
The response contains:
| Field | Use |
|---|---|
data.tenants[].id | The tenantId used in a report request |
data.tenants[].organization | The organization owning that tenant |
data.tenants[].sources | Source IDs and names available in the tenant |
meta.hasNext | Whether more tenants follow; increase offset by limit to request the next page |
Omit sourceId to include all sources in a tenant. sourceId identifies a collection source; a marketing source filter such as google is a different field.
3. Read Overview
Open Overview. Set:
| Parameter | Example |
|---|---|
tenantId | A tenant UUID from Workspace Access |
timeframe | last7days |
timezone | Europe/Istanbul |
interval | day |
Send the request. A successful response has success: true; data contains the report, including scoreCards and timeSeries. A valid empty report does not mean authentication failed.
The Reports API base URL is https://api.hardal.ai. Store your key as HARDAL_API_KEY and set HARDAL_TENANT_ID to the chosen UUID. Do not substitute your collection hostname.
curl --fail-with-body --get "https://api.hardal.ai/v1/reports/overview" \
--header "Authorization: Bearer ${HARDAL_API_KEY}" \
--data-urlencode "tenantId=${HARDAL_TENANT_ID}" \
--data-urlencode "timeframe=last7days" \
--data-urlencode "timezone=Europe/Istanbul" \
--data-urlencode "interval=day"
For a completed week, use timeframe=custom and explicit inclusive startDate and endDate values in YYYY-MM-DD format. Presets can include the current, incomplete day.
4. Use the result
A weekly reporting script can request a fixed date range, read data.scoreCards, and write those values to your own report or spreadsheet. Run that script in your own scheduler; retrieving a report does not create a scheduled job in Hardal.
Choose another endpoint when the question changes:
| Goal | Start with |
|---|---|
| Compare channels and campaigns | Acquisition |
| Analyze sales | Commerce Overview |
| Analyze event totals | Event Overview |
| Review AI agent activity | AI Visibility |
These are report endpoints, not an unrestricted raw-data export. Check each operation's response, pagination, and supported filters before building an integration.
Match the Dashboard
Use the same tenant, source, dates, timezone, and supported report configuration. For Acquisition, also match conversion events, attribution model, lookback window, and traffic scope. Do not assume every report uses the same filters or default timeframe.
Handle responses
| Status | Next step |
|---|---|
400 | Read the validation details and correct the request parameters |
401 | Check that the credential is present, valid, and not expired or revoked |
403 | Check the selected tenant and source against the credential's approved access |
429 | Respect Retry-After before retrying |
Keep the response requestId when asking support to investigate a failed request. Never include the API key in the support message.