Billing APIs

This document describes two billing-related APIs:

• Billing Excel Export API
• Billing Statistics API (Bill Stats API)

---

1. Billing Excel Export API

This API exports billing data based on filter conditions. The response is a binary Excel file stream.

1.1 API Info

• Endpoint: https://monitor.ponderera.com/bill/excel
• Method: POST
• Content-Type: application/json
• Description: Export billing details within a specified time range, optionally filtered by model or token.

---

1.2 Request (Request Parameters)

Headers

Name	Required	Type	Description	Example
token	Yes	String	Authentication token	************F99642E4AFF
Content-Type	Yes	String	Request content type	application/json

Body

Field	Required	Type	Description	Example
type	Yes	Integer	Export granularity (e.g. 1=minute, 2=hour, 3=day, 4=week, 5=month)	1
startTime	Yes	Long	Start timestamp (seconds)	1769443200
endTime	Yes	Long	End timestamp (seconds)	1769616000
tokenName	No	String	Filter by token name	***
modelName	No	String	Filter by model name	gemini-3-flash-preview

---

1.3 Response

Success

• Status: 200 OK
• Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• Body: Binary Excel file stream.

Failure

• 401 Unauthorized: Token missing or invalid.
• 400 Bad Request: Parameter validation failed (e.g. invalid timestamp format).

---

1.4 Example

cURL

curl --location 'https://monitor.ponderera.com/bill/excel' \
  --header 'token: ******' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": 1,
    "startTime": 1769443200,
    "endTime": 1769616000,
    "tokenName": "****",
    "modelName": "gemini-3-flash-preview"
  }' \
  --output bill_export.xlsx

---

2. Billing Statistics API (Bill Stats API)

This API returns aggregated usage statistics (e.g. token usage, duration, and cost) for a specific user over a time range, optionally filtered by token name or model name.

2.1 API Info

• Endpoint: https://monitor.ponderera.com/bill/stats
• Method: POST
• Content-Type: application/json

---

2.2 Request (Request Parameters)

Headers

Name	Required	Type	Description
token	Yes	String	Authentication token
Content-Type	Yes	String	Must be application/json

Body

Field	Required	Type	Example	Description
type	Yes	Integer	1	Aggregation granularity (e.g. 1=minute, 2=hour, 3=day, 4=week, 5=month)
startTime	Yes	Long	1769443200	Start timestamp (seconds)
endTime	Yes	Long	1769616000	End timestamp (seconds)
tokenName	No	String	"token1"	Filter statistics by a specific token name
modelName	No	String	"gemini-3-flash-preview"	Filter statistics by a specific model name

---

2.3 Response

Top-level structure

Field	Type	Description
message	String	Status message (e.g. "SUCCESS")
code	Integer	Status code (200 indicates success)
data	Array	Array of statistics entries

data item fields

Field	Type	Example	Description
time	String	"2026-02-06 00:00:00"	Aggregated time (formatted string)
timeGroup	Long	1770307200	Aggregated time as Unix timestamp (seconds)
userName	String	"admin"	User login name
tokenName	String	"token1"	Token name used
modelName	String	"gemini-3-flash-preview"	Model name
totalPromptTokens	Integer	8927	Total prompt tokens used
totalCompletionTokens	Integer	143	Total completion tokens used
totalCacheTokens	Integer	0	Total cache tokens used
totalCacheCreationTokens	Integer	0	Total cache creation tokens used
totalUseTime	Integer	6	Total usage time in seconds
callCount	Integer	1	Number of API calls in the period
totalAmount	Float	0.012588	Total cost in USD

---

2.4 Example

cURL

curl --location 'https://monitor.ponderera.com/bill/stats' \
  --header 'token: ******10B8F1532F0C82F99642E4AFF' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": 1,
    "startTime": 1769443200,
    "endTime": 1769616000,
    "tokenName": "token1",
    "modelName": "gemini-3-flash-preview"
  }'

Response example (JSON)

{
  "message": "SUCCESS",
  "code": 200,
  "data": [
    {
      "time": "2026-02-06 00:00:00",
      "timeGroup": 1770307200,
      "userName": "**",
      "tokenName": "Literature Extraction",
      "modelName": "gemini-3-flash-preview",
      "totalPromptTokens": 8927,
      "totalCompletionTokens": 143,
      "totalCacheTokens": 0,
      "totalCacheCreationTokens": 0,
      "totalUseTime": 6,
      "callCount": 1,
      "totalAmount": 0.012588
    }
  ]
}

Billing Excel Export API

This API exports billing data based on filter conditions. The response is a binary Excel file stream.

---

1. Basics

• Endpoint: https://monitor.ponderera.com/bill/excel
• Method: POST
• Content-Type: application/json
• Description: Export billing details within a specified time range, optionally filtered by model or token.

---

2. Request Parameters

Headers

Name	Required	Type	Description	Example
token	Yes	String	Authentication token	************F99642E4AFF
Content-Type	Yes	String	Request content type	application/json

Body

Field	Required	Type	Description	Example
type	Yes	Integer	Export granularity (e.g. 1=minute, 2=hour, 3=day, 4=week, 5=month)	1
startTime	Yes	Long	Start timestamp (seconds)	1769443200
endTime	Yes	Long	End timestamp (seconds)	1769616000
tokenName	No	String	Filter by token name	***
modelName	No	String	Filter by model name	gemini-3-flash-preview

---

3. Response

Success

• Status: 200 OK
• Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• Body: Binary Excel file stream.

Failure

• 401 Unauthorized: Token missing or invalid.
• 400 Bad Request: Parameter validation failed (e.g. invalid timestamp format).

---

4. Example

cURL

curl --location 'https://monitor.ponderera.com/bill/excel' \
  --header 'token: ******' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": 1,
    "startTime": 1769443200,
    "endTime": 1769616000,
    "tokenName": "****",
    "modelName": "gemini-3-flash-preview"
  }' \
  --output bill_export.xlsx