Billing Logs API

Overview

• Previously, clients integrated HyperVerge APIs directly, enabling them to track exact API hits for billing reconciliation.
• With the workflow orchestrator (HVOne), all API calls are handled by the SDK, and only the final result is returned. Clients have no direct way to reconcile usage.
• Data retention in Case Management or Results API is limited to 14 days, making monthly reconciliation difficult.

The Billing API solves this by allowing clients to fetch daily logs for cross-checking within the retention window.

How It Works

1. Daily Log Generation: HyperVerge generates a CSV file daily with all API calls per App ID for the previous day
2. API Fetch: Client hits the Billing API to download daily usage logs
3. Storage & Reconciliation: Client stores hits in their database, cross-verifies with Results API, Case Management, and monthly logs

---

API Documentation

Endpoint

POST /v1/logs/module/daily

Base URL

https://billing-dashboard.hyperverge.co

Headers

Key	Value	Description
appid	<HYPERVERGE_APPID>	Application ID for authentication
appkey	<HYPERVERGE_APPKEY>	Application key for authentication
Content-Type	application/json	Request body format

Request Body

{
    "date": "2023-11-01"
}

Parameter	Type	Required	Description
date	string	Yes	Date for which logs are requested (Format: YYYY-MM-DD). Must be a past date, available after 10am of the next day

Success Response (200 OK)

{
    "status": "success",
    "data": {
        "url": "s3Url"
    }
}

Key	Type	Description
status	string	Status of the request
url	string	URL to the log file in S3. Valid for 15 minutes only.

Error Responses

Status Code	Message	Description
400	Validation Failed	Date missing or invalid format
401	Missing/Invalid credentials	Invalid appId or appKey
404	File not found	Log file for the date doesn't exist
422	Invalid date	Wrong format or future date
500	Internal Server Error	Unexpected server error

Example cURL

curl --location 'https://billing-dashboard.hyperverge.co/v1/logs/module/daily' \
--header 'appid: <HYPERVERGE_APPID>' \
--header 'appkey: <HYPERVERGE_APPKEY>' \
--header 'Content-Type: application/json' \
--data '{
    "date": "2023-11-01"
}'

CSV Structure

Field Name	Description
requestid	Unique identifier for each request
appid	App ID used for the request
reference_id	Reference identifier
transaction_id	Transaction ID associated with the request
statuscode	HTTP status code returned by the API
originalurl	API endpoint URL where the request was sent
event_timestamp	Date and time (UTC) when the request was initiated

---

FAQs

Why a separate API instead of returning billing logs in the Results API?

Tying billing logs to the Results API could lead to reconciliation gaps if the client misses any edge cases (e.g., user killing app mid-journey, calls spanning month boundaries). The Billing API is simpler — clients either get all hits from a day or none.

Why can logs only be fetched after 10am of the next day?

To account for other timezones + time to process and prepare the logs.

Does the API support date range as input?

Not currently, as there's no identified need for this.

Instead of originalUrl, can we return Module & SubModule names?

This feature is currently under evaluation.