Skip to content

Commit 2b7180a

Browse files
chris-young-heliuschris-young-helius
authored
Merge pull request #586 from helius-labs/chris-young-helius/admin-api
Adds Admin API documentation
2 parents 410599e + 3b39e35 commit 2b7180a

File tree

4 files changed

+387
-0
lines changed

4 files changed

+387
-0
lines changed

‎api-reference/admin.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: 'Admin API'
3+
"og:title": "Admin API - Helius"
4+
sidebarTitle: 'Overview'
5+
description: 'Programmatic access to project usage and billing data via API key authentication.'
6+
"og:description": "Retrieve credit usage, subscription details, and per-service request counts for your Helius projects."
7+
---
8+
9+
## What is the Admin API?
10+
11+
The Admin API provides programmatic access to your project's usage and billing data. Use it to monitor credit consumption, track per-service request counts, and retrieve subscription details — all authenticated with your standard Helius API key.
12+
13+
This is useful for building internal dashboards, automating usage alerts, or integrating Helius billing data into your own systems.
14+
15+
## Authentication
16+
17+
The Admin API uses API key authentication (the same key you use for RPC and other Helius APIs). You can provide your key in one of two ways:
18+
19+
- **Header**: `X-Api-Key: YOUR_API_KEY`
20+
- **Query parameter**: `?api-key=YOUR_API_KEY`
21+
22+
<Note>
23+
The API key must belong to the project you're querying. Requests where the API key's project does not match the project ID in the path will return a `400` error.
24+
</Note>
25+
26+
## Rate Limits
27+
28+
The Admin API is rate-limited to **5 requests per second** per project.
29+
30+
## Endpoints
31+
32+
<CardGroup cols={2}>
33+
<Card title="Get Project Usage" href="/api-reference/admin/get-project-usage">
34+
Retrieve credit usage, subscription details, and per-service request counts for the current billing cycle.
35+
</Card>
36+
</CardGroup>

‎api-reference/admin/get-project-usage.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: "Get Project Usage"
3+
"og:title": "Get Project Usage - Helius Admin API"
4+
sidebarTitle: "Get Project Usage"
5+
description: "Retrieve credit usage, subscription details, and per-service request counts for a project within the current billing cycle."
6+
"og:description": "Get credit usage, billing details, and request counts for a Helius project"
7+
openapi: "/openapi/admin-api/getProjectUsage.yaml GET /v0/admin/projects/{id}/usage"
8+
---
9+
10+
## Overview
11+
12+
Returns a complete picture of a project's credit consumption for the current billing cycle, including credits remaining, subscription plan details, and a breakdown of requests by service type (RPC, DAS, gRPC, WebSocket, etc.).
13+
14+
## Request Parameters
15+
16+
<ParamField path="id" type="string" required>
17+
The project ID to retrieve usage for. Must match the project associated with the API key used for authentication.
18+
</ParamField>
19+
20+
## Response Fields
21+
22+
<ParamField body="creditsRemaining" type="number">
23+
Credits remaining in the current billing cycle. Calculated as the plan's credit limit minus regular credits consumed, floored at zero.
24+
</ParamField>
25+
26+
<ParamField body="creditsUsed" type="number">
27+
Total credits consumed in the current billing cycle, including both regular and prepaid credits.
28+
</ParamField>
29+
30+
<ParamField body="prepaidCreditsRemaining" type="number">
31+
Prepaid credits still available.
32+
</ParamField>
33+
34+
<ParamField body="prepaidCreditsUsed" type="number">
35+
Prepaid credits consumed in the current billing cycle.
36+
</ParamField>
37+
38+
<ParamField body="subscriptionDetails" type="object">
39+
Subscription plan and billing cycle information.
40+
</ParamField>
41+
42+
<ParamField body="subscriptionDetails.billingCycle.start" type="string">
43+
Billing cycle start date in `YYYY-MM-DD` format.
44+
</ParamField>
45+
46+
<ParamField body="subscriptionDetails.billingCycle.end" type="string">
47+
Billing cycle end date in `YYYY-MM-DD` format.
48+
</ParamField>
49+
50+
<ParamField body="subscriptionDetails.creditsLimit" type="number">
51+
Total credit allowance for the billing cycle based on your plan.
52+
</ParamField>
53+
54+
<ParamField body="subscriptionDetails.plan" type="string">
55+
The name of the subscription plan (e.g., `"business"`, `"professional"`).
56+
</ParamField>
57+
58+
<ParamField body="usage" type="object">
59+
Request counts broken down by service type. Each field is the total number of requests made to that service during the current billing cycle.
60+
</ParamField>
61+
62+
<ParamField body="usage.api" type="number">
63+
Enhanced API requests (e.g., parsed transactions, token metadata).
64+
</ParamField>
65+
66+
<ParamField body="usage.archival" type="number">
67+
Archival RPC requests.
68+
</ParamField>
69+
70+
<ParamField body="usage.das" type="number">
71+
DAS (Digital Asset Standard) API requests.
72+
</ParamField>
73+
74+
<ParamField body="usage.grpc" type="number">
75+
gRPC streaming requests.
76+
</ParamField>
77+
78+
<ParamField body="usage.grpcGeyser" type="number">
79+
Geyser gRPC requests.
80+
</ParamField>
81+
82+
<ParamField body="usage.photon" type="number">
83+
ZK Compression (Photon) requests.
84+
</ParamField>
85+
86+
<ParamField body="usage.rpc" type="number">
87+
Standard Solana RPC requests.
88+
</ParamField>
89+
90+
<ParamField body="usage.stream" type="number">
91+
LaserStream data streaming requests.
92+
</ParamField>
93+
94+
<ParamField body="usage.webhook" type="number">
95+
Webhook delivery events.
96+
</ParamField>
97+
98+
<ParamField body="usage.websocket" type="number">
99+
WebSocket subscription requests.
100+
</ParamField>

‎docs.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -602,6 +602,19 @@
602602
}
603603
]
604604
},
605+
{
606+
"group": "Account Management APIs",
607+
"pages": [
608+
{
609+
"group": "Admin",
610+
"icon": "shield-halved",
611+
"pages": [
612+
"api-reference/admin",
613+
"api-reference/admin/get-project-usage"
614+
]
615+
}
616+
]
617+
},
605618
{
606619
"group": "Deprecated APIs",
607620
"pages": [

‎openapi/admin-api/getProjectUsage.yaml‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
openapi: 3.0.3
2+
info:
3+
title: Helius Admin API
4+
description: |
5+
Programmatic access to project usage and billing data.
6+
7+
## Authentication
8+
9+
All requests require an API key passed either as:
10+
- Header: `X-Api-Key: YOUR_API_KEY`
11+
- Query parameter: `?api-key=YOUR_API_KEY`
12+
version: 1.0.0
13+
contact:
14+
name: API Support
15+
url: https://helius.dev
16+
17+
servers:
18+
- url: https://api.helius.xyz
19+
description: Production server
20+
21+
security:
22+
- ApiKeyQuery: []
23+
- ApiKeyHeader: []
24+
25+
components:
26+
securitySchemes:
27+
ApiKeyQuery:
28+
type: apiKey
29+
in: query
30+
name: api-key
31+
description: API key passed as a query parameter.
32+
ApiKeyHeader:
33+
type: apiKey
34+
in: header
35+
name: X-Api-Key
36+
description: API key passed as a request header.
37+
38+
schemas:
39+
ProjectUsageResponse:
40+
type: object
41+
properties:
42+
creditsRemaining:
43+
type: number
44+
description: Number of credits remaining in the current billing cycle. Calculated as `creditsLimit - regularCreditsUsed`, floored at 0.
45+
example: 487500
46+
creditsUsed:
47+
type: number
48+
description: Total credits consumed in the current billing cycle, including both regular and prepaid credits.
49+
example: 12500
50+
prepaidCreditsRemaining:
51+
type: number
52+
description: Number of prepaid credits remaining.
53+
example: 50000
54+
prepaidCreditsUsed:
55+
type: number
56+
description: Number of prepaid credits consumed in the current billing cycle.
57+
example: 0
58+
subscriptionDetails:
59+
type: object
60+
description: Details about the project's subscription plan and current billing cycle.
61+
properties:
62+
billingCycle:
63+
type: object
64+
description: Start and end dates of the current billing cycle.
65+
properties:
66+
start:
67+
type: string
68+
description: Billing cycle start date.
69+
example: "2026-04-01"
70+
end:
71+
type: string
72+
description: Billing cycle end date.
73+
example: "2026-05-01"
74+
creditsLimit:
75+
type: number
76+
description: Total credit allowance for the current billing cycle based on the plan.
77+
example: 500000
78+
plan:
79+
type: string
80+
description: The name of the subscription plan.
81+
example: "business"
82+
usage:
83+
type: object
84+
description: Request counts broken down by service type for the current billing cycle.
85+
properties:
86+
api:
87+
type: number
88+
description: Number of Enhanced API requests (e.g., parsed transactions, token metadata).
89+
example: 1200
90+
archival:
91+
type: number
92+
description: Number of archival RPC requests.
93+
example: 0
94+
das:
95+
type: number
96+
description: Number of DAS (Digital Asset Standard) API requests.
97+
example: 5000
98+
grpc:
99+
type: number
100+
description: Number of gRPC streaming requests.
101+
example: 300
102+
grpcGeyser:
103+
type: number
104+
description: Number of Geyser gRPC requests.
105+
example: 0
106+
photon:
107+
type: number
108+
description: Number of ZK Compression (Photon) requests.
109+
example: 0
110+
rpc:
111+
type: number
112+
description: Number of standard Solana RPC requests.
113+
example: 4500
114+
stream:
115+
type: number
116+
description: Number of LaserStream data streaming requests.
117+
example: 100
118+
webhook:
119+
type: number
120+
description: Number of webhook delivery events.
121+
example: 800
122+
websocket:
123+
type: number
124+
description: Number of WebSocket subscription requests.
125+
example: 600
126+
127+
ErrorResponse:
128+
type: object
129+
properties:
130+
statusCode:
131+
type: integer
132+
description: HTTP status code.
133+
message:
134+
type: string
135+
description: Human-readable error message.
136+
error:
137+
type: string
138+
description: HTTP error name.
139+
140+
paths:
141+
/v0/admin/projects/{id}/usage:
142+
get:
143+
tags:
144+
- Admin
145+
summary: Get Project Usage
146+
operationId: getProjectUsage
147+
description: |
148+
Retrieve credit usage, subscription details, and per-service request counts for a project within the current billing cycle.
149+
150+
The API key used for authentication must belong to the project specified in the path. Requests where the API key's project does not match the `id` parameter will return a `400` error.
151+
parameters:
152+
- name: id
153+
in: path
154+
required: true
155+
description: The project ID to retrieve usage for. Must match the project associated with the API key.
156+
schema:
157+
type: string
158+
format: uuid
159+
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
160+
responses:
161+
'200':
162+
description: Project usage retrieved successfully.
163+
content:
164+
application/json:
165+
schema:
166+
$ref: '#/components/schemas/ProjectUsageResponse'
167+
example:
168+
creditsRemaining: 487500
169+
creditsUsed: 12500
170+
prepaidCreditsRemaining: 50000
171+
prepaidCreditsUsed: 0
172+
subscriptionDetails:
173+
billingCycle:
174+
start: "2026-04-01"
175+
end: "2026-05-01"
176+
creditsLimit: 500000
177+
plan: "business"
178+
usage:
179+
api: 1200
180+
archival: 0
181+
das: 5000
182+
grpc: 300
183+
grpcGeyser: 0
184+
photon: 0
185+
rpc: 4500
186+
stream: 100
187+
webhook: 800
188+
websocket: 600
189+
'400':
190+
description: Bad Request — the project ID in the path does not match the project associated with the API key.
191+
content:
192+
application/json:
193+
schema:
194+
$ref: '#/components/schemas/ErrorResponse'
195+
example:
196+
statusCode: 400
197+
message: "Invalid project id"
198+
error: "Bad Request"
199+
'401':
200+
description: Unauthorized — API key is missing, malformed, or not found.
201+
content:
202+
application/json:
203+
schema:
204+
$ref: '#/components/schemas/ErrorResponse'
205+
example:
206+
statusCode: 401
207+
message: "Missing or invalid API key"
208+
error: "Unauthorized"
209+
'403':
210+
description: Forbidden — the Admin API is not enabled for this project.
211+
content:
212+
application/json:
213+
schema:
214+
$ref: '#/components/schemas/ErrorResponse'
215+
example:
216+
statusCode: 403
217+
message: "Admin API not enabled for this project"
218+
error: "Forbidden"
219+
'429':
220+
description: Too Many Requests — rate limit of 5 requests per second exceeded.
221+
content:
222+
application/json:
223+
schema:
224+
$ref: '#/components/schemas/ErrorResponse'
225+
example:
226+
statusCode: 429
227+
message: "ThrottlerException: Too Many Requests"
228+
error: "Too Many Requests"
229+
'500':
230+
description: Internal Server Error — a server-side error occurred (e.g., missing billing data).
231+
content:
232+
application/json:
233+
schema:
234+
$ref: '#/components/schemas/ErrorResponse'
235+
example:
236+
statusCode: 500
237+
message: "Internal server error"
238+
error: "Internal Server Error"

0 commit comments

Comments
 (0)