Skip to content

Commit 82d2aa2

Browse files
Lookoff-AIMLAPILookoff-AIMLAPI
authored
Merge pull request #444 from aimlapi/agent/add-v2-usage-docs
Add API Key Usage docs for /v2/usage and /v2/usage/detail
2 parents 6e28bd4 + bc7774b commit 82d2aa2

4 files changed

Lines changed: 368 additions & 0 deletions

File tree

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
* [🟡 Service Endpoints](api-references/service-endpoints/README.md)
1515
* [Account Balance](api-references/service-endpoints/account-balance.md)
1616
* [API Key Management](api-references/service-endpoints/api-key-management.md)
17+
* [API Key Usage](api-references/service-endpoints/api-key-usage.md)
1718
* [Complete Model List](api-references/service-endpoints/complete-model-list.md)
1819
* [All Model IDs](api-references/model-database.md)
1920
* [Text Models (LLM)](api-references/text-models-llm/README.md)

‎docs/api-references/service-endpoints/api-key-usage.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# API Key Usage
2+
3+
Query how much a given API key spent over a period of time.\
4+
To make a request, you only need your AIMLAPI key obtained from your [account dashboard](https://aimlapi.com/app/keys).
5+
6+
Both endpoints take the same parameters and differ only in what they return: `/v2/usage/detail` adds a per-model breakdown.
7+
8+
## Choosing the time window
9+
10+
Pass **either** `period` **or** both `start` and `end` — not both at once:
11+
12+
* `period` is relative — `24h`, `7d`, that is a positive integer followed by `h` or `d`.
13+
* `start` and `end` are absolute ISO-8601 timestamps.
14+
15+
The window cannot exceed **92 days**. For a longer report, request several windows and add them up.
16+
17+
{% hint style="info" %}
18+
A timestamp without a UTC offset is read as **UTC**, not as your local time. Pass an explicit offset (`2026-07-01T00:00:00+03:00`) if you mean something else.
19+
20+
The response always echoes `start` and `end` resolved to UTC, so you can see exactly which window was measured.
21+
{% endhint %}
22+
23+
## Choosing the key
24+
25+
| Your key | `key_prefix` | Result |
26+
| ---------------- | ------------------------ | ---------------- |
27+
| any key | omitted | its own spend |
28+
| management key | provided | that key's spend |
29+
| regular key | provided, its own prefix | its own spend |
30+
| regular key | provided, another prefix | `403` |
31+
32+
Any key can read its own spend. Reading the spend of a **different** key requires a management key.
33+
34+
## Get key usage
35+
36+
Returns the total spend for a key over the requested window.
37+
38+
{% openapi-operation spec="usage-v2" path="/v2/usage" method="get" %}
39+
[OpenAPI usage-v2](https://raw.githubusercontent.com/aimlapi/api-docs/refs/heads/main/docs/api-references/service-endpoints/usage-v2.json)
40+
{% endopenapi-operation %}
41+
42+
## Get detailed key usage
43+
44+
Returns the same total plus a per-model breakdown, sorted by spend.
45+
46+
{% openapi-operation spec="usage-detail-v2" path="/v2/usage/detail" method="get" %}
47+
[OpenAPI usage-detail-v2](https://raw.githubusercontent.com/aimlapi/api-docs/refs/heads/main/docs/api-references/service-endpoints/usage-detail-v2.json)
48+
{% endopenapi-operation %}
49+
50+
## Good to know
51+
52+
* **`spend` is the authoritative total.** In the detailed response it is computed from the total rather than by adding up `models`, so the two can differ by a few nano-dollars. That is expected.
53+
* **Unfinished work is not counted.** A video generation that is still running is excluded until it completes.
54+
* **This is not your balance.** These endpoints answer "what did this key cost", which is useful for cost attribution and budgeting. For your current balance use [Account Balance](account-balance.md).
55+
* **Polling?** Prefer `period`. Responses are cached briefly per exact window, and a hand-built timestamp that changes on every call never reuses that cache.
56+
57+
## Errors
58+
59+
| Code | Meaning |
60+
| ----- | ---------------------------------------------------------------------------------------------------------------------- |
61+
| `400` | No window given, both window forms given at once, a malformed date or period, `end` earlier than `start`, or over 92 days |
62+
| `401` | Missing or invalid API key |
63+
| `403` | A regular key asked for another key's prefix |
64+
| `404` | The prefix does not belong to your account |
65+
| `429` | Too many requests |

‎docs/api-references/service-endpoints/usage-detail-v2.json‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
{
2+
"openapi": "3.0.0",
3+
"info": {
4+
"title": "AIML API",
5+
"version": "1.0.0"
6+
},
7+
"servers": [
8+
{
9+
"url": "https://api.aimlapi.com"
10+
}
11+
],
12+
"paths": {
13+
"/v2/usage/detail": {
14+
"get": {
15+
"operationId": "_v2_usage_detail",
16+
"parameters": [
17+
{
18+
"name": "period",
19+
"in": "query",
20+
"required": false,
21+
"description": "Relative window: a positive integer followed by `h` or `d`, for example `24h` or `7d`. Provide either `period` or both `start` and `end`, never both.",
22+
"schema": {
23+
"type": "string",
24+
"example": "7d"
25+
}
26+
},
27+
{
28+
"name": "start",
29+
"in": "query",
30+
"required": false,
31+
"description": "Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with `end`.",
32+
"schema": {
33+
"type": "string",
34+
"example": "2026-07-01T00:00:00Z"
35+
}
36+
},
37+
{
38+
"name": "end",
39+
"in": "query",
40+
"required": false,
41+
"description": "Window end, ISO-8601. Must not be earlier than `start`, and the window must not exceed 92 days.",
42+
"schema": {
43+
"type": "string",
44+
"example": "2026-07-28T00:00:00Z"
45+
}
46+
},
47+
{
48+
"name": "key_prefix",
49+
"in": "query",
50+
"required": false,
51+
"description": "Prefix of the key to report on. Omit it to get the spend of the key you are authenticating with. Reporting on a different key requires a management key.",
52+
"schema": {
53+
"type": "string",
54+
"example": "abcd1234"
55+
}
56+
}
57+
],
58+
"responses": {
59+
"200": {
60+
"content": {
61+
"application/json": {
62+
"schema": {
63+
"type": "object",
64+
"properties": {
65+
"api_key_prefix": {
66+
"type": "string",
67+
"nullable": true,
68+
"description": "The requested key prefix, or null when it was omitted and the answer is your own key's spend.",
69+
"example": "abcd1234"
70+
},
71+
"start": {
72+
"type": "string",
73+
"description": "Window start, resolved to UTC.",
74+
"example": "2026-07-20T22:15:00.000Z"
75+
},
76+
"end": {
77+
"type": "string",
78+
"description": "Window end, resolved to UTC.",
79+
"example": "2026-07-27T22:15:00.000Z"
80+
},
81+
"spend": {
82+
"type": "number",
83+
"description": "Total spend for the key over the window, in USD. This is the authoritative total: it is computed from the total, not by adding up models, so it can differ from that sum by a few nano-dollars.",
84+
"example": 12.3456
85+
},
86+
"currency": {
87+
"type": "string",
88+
"description": "Spend currency (always USD).",
89+
"example": "USD"
90+
},
91+
"requests": {
92+
"type": "integer",
93+
"description": "Number of charged requests in the window.",
94+
"example": 842
95+
},
96+
"models": {
97+
"type": "array",
98+
"description": "Per-model breakdown, highest spend first.",
99+
"items": {
100+
"type": "object",
101+
"properties": {
102+
"model": {
103+
"type": "string",
104+
"description": "Model name.",
105+
"example": "openai/gpt-5"
106+
},
107+
"spend": {
108+
"type": "number",
109+
"description": "Spend for this model, in USD.",
110+
"example": 8.12
111+
},
112+
"requests": {
113+
"type": "integer",
114+
"description": "Charged requests for this model.",
115+
"example": 500
116+
}
117+
},
118+
"required": ["model", "spend", "requests"]
119+
}
120+
}
121+
},
122+
"required": [
123+
"api_key_prefix",
124+
"start",
125+
"end",
126+
"spend",
127+
"currency",
128+
"requests",
129+
"models"
130+
]
131+
}
132+
}
133+
}
134+
}
135+
},
136+
"x-hideTryItPanel": true,
137+
"x-codeSamples": [
138+
{
139+
"lang": "cURL",
140+
"source": "curl -L \\\n --request GET \\\n --url 'https://api.aimlapi.com/v2/usage/detail?key_prefix=abcd1234&period=7d' \\\n --header 'Authorization: Bearer <YOUR_AIMLAPI_MANAGEMENT_KEY>'"
141+
},
142+
{
143+
"lang": "JavaScript",
144+
"source": "async function main() {\n const url = new URL(\"https://api.aimlapi.com/v2/usage/detail\");\n url.searchParams.set(\"key_prefix\", \"abcd1234\");\n url.searchParams.set(\"period\", \"7d\");\n\n const response = await fetch(url, {\n headers: {\n \"Authorization\": \"Bearer <YOUR_AIMLAPI_MANAGEMENT_KEY>\",\n },\n });\n\n const data = await response.json();\n console.log(JSON.stringify(data, null, 2));\n}\n\nmain();"
145+
},
146+
{
147+
"lang": "Python",
148+
"source": "import requests\nimport json\n\ndef main():\n response = requests.get(\n \"https://api.aimlapi.com/v2/usage/detail\",\n headers={\n # Insert your AIML API management key instead of <YOUR_AIMLAPI_MANAGEMENT_KEY>:\n \"Authorization\": \"Bearer <YOUR_AIMLAPI_MANAGEMENT_KEY>\",\n },\n params={\"key_prefix\": \"abcd1234\", \"period\": \"7d\"}\n )\n\n data = response.json()\n print(json.dumps(data, indent=2, ensure_ascii=False))\n\nif __name__ == \"__main__\":\n main()"
149+
}
150+
]
151+
}
152+
}
153+
},
154+
"components": {
155+
"securitySchemes": {
156+
"access-token": {
157+
"scheme": "bearer",
158+
"bearerFormat": "<YOUR_AIMLAPI_KEY>",
159+
"type": "http",
160+
"description": "Bearer key"
161+
}
162+
}
163+
}
164+
}

‎docs/api-references/service-endpoints/usage-v2.json‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
{
2+
"openapi": "3.0.0",
3+
"info": {
4+
"title": "AIML API",
5+
"version": "1.0.0"
6+
},
7+
"servers": [
8+
{
9+
"url": "https://api.aimlapi.com"
10+
}
11+
],
12+
"paths": {
13+
"/v2/usage": {
14+
"get": {
15+
"operationId": "_v2_usage",
16+
"parameters": [
17+
{
18+
"name": "period",
19+
"in": "query",
20+
"required": false,
21+
"description": "Relative window: a positive integer followed by `h` or `d`, for example `24h` or `7d`. Provide either `period` or both `start` and `end`, never both.",
22+
"schema": {
23+
"type": "string",
24+
"example": "24h"
25+
}
26+
},
27+
{
28+
"name": "start",
29+
"in": "query",
30+
"required": false,
31+
"description": "Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with `end`.",
32+
"schema": {
33+
"type": "string",
34+
"example": "2026-07-01T00:00:00Z"
35+
}
36+
},
37+
{
38+
"name": "end",
39+
"in": "query",
40+
"required": false,
41+
"description": "Window end, ISO-8601. Must not be earlier than `start`, and the window must not exceed 92 days.",
42+
"schema": {
43+
"type": "string",
44+
"example": "2026-07-28T00:00:00Z"
45+
}
46+
},
47+
{
48+
"name": "key_prefix",
49+
"in": "query",
50+
"required": false,
51+
"description": "Prefix of the key to report on. Omit it to get the spend of the key you are authenticating with. Reporting on a different key requires a management key.",
52+
"schema": {
53+
"type": "string",
54+
"example": "abcd1234"
55+
}
56+
}
57+
],
58+
"responses": {
59+
"200": {
60+
"content": {
61+
"application/json": {
62+
"schema": {
63+
"type": "object",
64+
"properties": {
65+
"api_key_prefix": {
66+
"type": "string",
67+
"nullable": true,
68+
"description": "The requested key prefix, or null when it was omitted and the answer is your own key's spend.",
69+
"example": "abcd1234"
70+
},
71+
"start": {
72+
"type": "string",
73+
"description": "Window start, resolved to UTC.",
74+
"example": "2026-07-26T22:15:00.000Z"
75+
},
76+
"end": {
77+
"type": "string",
78+
"description": "Window end, resolved to UTC.",
79+
"example": "2026-07-27T22:15:00.000Z"
80+
},
81+
"spend": {
82+
"type": "number",
83+
"description": "Total spend for the key over the window, in USD.",
84+
"example": 13.704199
85+
},
86+
"currency": {
87+
"type": "string",
88+
"description": "Spend currency (always USD).",
89+
"example": "USD"
90+
},
91+
"requests": {
92+
"type": "integer",
93+
"description": "Number of charged requests in the window.",
94+
"example": 9643
95+
}
96+
},
97+
"required": [
98+
"api_key_prefix",
99+
"start",
100+
"end",
101+
"spend",
102+
"currency",
103+
"requests"
104+
]
105+
}
106+
}
107+
}
108+
}
109+
},
110+
"x-hideTryItPanel": true,
111+
"x-codeSamples": [
112+
{
113+
"lang": "cURL",
114+
"source": "curl -L \\\n --request GET \\\n --url 'https://api.aimlapi.com/v2/usage?period=24h' \\\n --header 'Authorization: Bearer <YOUR_AIMLAPI_KEY>'"
115+
},
116+
{
117+
"lang": "JavaScript",
118+
"source": "async function main() {\n const response = await fetch(\"https://api.aimlapi.com/v2/usage?period=24h\", {\n headers: {\n \"Authorization\": \"Bearer <YOUR_AIMLAPI_KEY>\",\n },\n });\n\n const data = await response.json();\n console.log(JSON.stringify(data, null, 2));\n}\n\nmain();"
119+
},
120+
{
121+
"lang": "Python",
122+
"source": "import requests\nimport json\n\ndef main():\n response = requests.get(\n \"https://api.aimlapi.com/v2/usage\",\n headers={\n # Insert your AIML API Key instead of <YOUR_AIMLAPI_KEY>:\n \"Authorization\": \"Bearer <YOUR_AIMLAPI_KEY>\",\n },\n params={\"period\": \"24h\"}\n )\n\n data = response.json()\n print(json.dumps(data, indent=2, ensure_ascii=False))\n\nif __name__ == \"__main__\":\n main()"
123+
}
124+
]
125+
}
126+
}
127+
},
128+
"components": {
129+
"securitySchemes": {
130+
"access-token": {
131+
"scheme": "bearer",
132+
"bearerFormat": "<YOUR_AIMLAPI_KEY>",
133+
"type": "http",
134+
"description": "Bearer key"
135+
}
136+
}
137+
}
138+
}

0 commit comments

Comments
 (0)