Clicks API Documentation

Overview

The Clicks API returns daily click aggregates for advertisers within a requested date range (one row per advertiser per click_date). It is designed for analytics workflows, answer engines, and AI agents that need raw click activity instead of a pre-ranked materialized report snapshot.

Endpoint details

API Playground

Use the examples below to inspect click rows for a fixed date range. Publisher users automatically get their own publisher; admins can optionally pass publisher_id. Sign in to enable live testing with your API key.

Parameters

Response format

JSON object with data (click rows) and meta (pagination + request context):

{
  "data": [
    {
      "advertiser_id": 123,
      "advertiser_name": "Alpha Store",
      "advertiser_slug": "alpha-store",
      "publisher_id": 45,
      "publisher_name": "Example Publisher",
      "network_id": 7,
      "network_name": "Awin",
      "click_date": "2026-03-31",
      "click_count": 120
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 100,
    "used_searchkick": true,
    "start_date": "2026-03-01",
    "end_date": "2026-03-31",
    "days": 31,
    "publisher_id": 45
  }
}

Pagination

The Clicks API uses offset-style pagination via page and per_page (or limit). Use meta.next_page to walk additional pages; meta.total_count reflects the full matching row count for the date window and publisher scope.

• meta.current_page – Current page (1-based)
• meta.next_page / meta.prev_page – Adjacent page numbers, or null at boundaries
• meta.used_searchkick – true when Searchkick served the query; false when SQL fallback was used

MCP access

MCP clients can call this endpoint directly with the named get_clicks tool. The generic api_request tool also works, but get_clicks gives agents a cleaner schema for date-range click analysis. MCP accepts start_date/end_date and aliases date_from/date_to or from/to.

{
  "name": "get_clicks",
  "arguments": {
    "start_date": "2026-03-01",
    "end_date": "2026-03-31",
    "publisher_id": 1338
  }
}

Examples

Fetch clicks for a date range

curl -H "X-Api-Key: YOUR_KEY" \
  "https://app.hienergy.ai/api/v1/clicks?start_date=2026-03-01&end_date=2026-03-31"

Admin filter for one publisher

curl -H "X-Api-Key: YOUR_KEY" \
  "https://app.hienergy.ai/api/v1/clicks?start_date=2026-03-01&end_date=2026-03-31&publisher_id=1338"

Fetch OpenAPI schema

curl -H "X-Api-Key: YOUR_KEY" \
  "https://app.hienergy.ai/api/v1/schema"

Error handling

The API returns structured error responses with an error object:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Date range cannot exceed 90 days"
  }
}

When Searchkick is healthy, queries use the search index. If Searchkick is unavailable or search execution fails, the API falls back to SQL and still returns 200 with the same shape; check meta.used_searchkick.

OpenAPI

The full machine-readable contract is available at GET /api/v1/schema (OpenAPI 3.0.3). Browse the listClicks operation for parameter and response schemas.