> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Account
> Your team's plan, billing mode, credit balance, storage and provider keys
## Overview
Returns the team behind your API key. Call it before a batch to know whether the videos will go through:
* **`billingMode`**: `managed` means generation runs on Hooked's provider keys and is paid with credits; `byok` means your team generates with its own provider keys (Settings → AI keys in the dashboard) and no credits are taken.
* **`plan`**: the plan, its subscription status and the next renewal. A managed team needs a live plan (`active`, `trialing` or `past_due`) to generate.
* **`credits.balance`**: credits left (the plan's plus any extra credits). `chargedForGeneration` is `true` on managed and `false` on byok, where the balance is shown but not spent on generation.
* **`storage`**: bytes used by your library and videos, and your plan's limit.
* **`keys`** (byok only, `null` on managed): one entry per provider with `configured` and `status` (`ok`, `missing` or `invalid`). Which keys a format needs is listed on each create page and in [Creating videos](/guides/creating-videos#credits-and-your-own-keys).
Key values never leave Hooked: not the key, not a hint of it. Free and safe to call as often as you like.
```bash cURL theme={null}
curl "https://api.hooked.so/v1/account" \
-H "x-api-key: your_api_key_here"
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.hooked.so/v1/account", {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data: account } = await response.json();
if (account.billingMode === "byok") {
const broken = account.keys.filter((key) => key.status !== "ok").map((key) => key.provider);
if (broken.length) console.warn("Fix these keys first:", broken);
} else if (account.credits.balance < 500) {
console.warn("Low on credits:", account.credits.balance);
}
```
```python Python theme={null}
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/account",
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
account = response.json()["data"]
print(account["billingMode"], account["credits"]["balance"])
```
```json managed theme={null}
{
"success": true,
"message": "Account fetched successfully",
"data": {
"team": { "id": "cm4w0team0001ab12cd34ef56", "name": "Acme Growth" },
"billingMode": "managed",
"plan": { "name": "pro", "status": "active", "renewsAt": "2026-11-01T00:00:00.000Z" },
"credits": { "balance": 1840, "chargedForGeneration": true },
"storage": { "usedBytes": 3221225472, "limitBytes": 53687091200 },
"keys": null
}
}
```
```json byok theme={null}
{
"success": true,
"message": "Account fetched successfully",
"data": {
"team": { "id": "cm4w0team0001ab12cd34ef56", "name": "Acme Growth" },
"billingMode": "byok",
"plan": { "name": "starter", "status": "active", "renewsAt": "2026-11-01T00:00:00.000Z" },
"credits": { "balance": 0, "chargedForGeneration": false },
"storage": { "usedBytes": 524288000, "limitBytes": 10737418240 },
"keys": [
{ "provider": "openrouter", "configured": true, "status": "ok" },
{ "provider": "elevenlabs", "configured": true, "status": "invalid" },
{ "provider": "firecrawl", "configured": false, "status": "missing" },
{ "provider": "bria", "configured": false, "status": "missing" },
{ "provider": "gemini", "configured": true, "status": "ok" }
]
}
}
```
## Errors
| Status | When |
| - | - |
| 401 | Missing or invalid API key (`code: "not_authenticated"`) |
| 403 | The team does not have the Hooked app product (`code: "entitlement_required"`) |
## OpenAPI
````yaml GET /v1/account
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Videos
description: Create projects, follow them and render videos
- name: Account Analysis
description: Analyze TikTok and YouTube accounts
- name: Channels
description: Connected social accounts you publish to
- name: Publish
description: Schedule videos to your connected accounts
- name: Images
description: 'Image editing: background removal and expansion'
- name: Media
description: 'Your media library: list, import from a URL, upload a file'
- name: Avatars
description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
/v1/account:
get:
tags: []
summary: Get Account
description: >-
The team behind your API key: plan, billing mode, credit balance,
storage and, for a byok team, which provider keys are set and working.
Never returns a key value. Free and safe to call before a batch to check
the balance.
operationId: getAccount
responses:
'200':
description: The account
content:
application/json:
schema:
type: object
required:
- success
- data
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/Account'
message:
type: string
example:
success: true
message: Account fetched successfully
data:
team:
id: cm4w0team0001ab12cd34ef56
name: Acme Growth
billingMode: managed
plan:
name: pro
status: active
renewsAt: '2026-11-01T00:00:00.000Z'
credits:
balance: 1840
chargedForGeneration: true
storage:
usedBytes: 3221225472
limitBytes: 53687091200
keys: null
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/EntitlementRequired'
'429':
$ref: '#/components/responses/RateLimited429'
'500':
$ref: '#/components/responses/InternalError'
security:
- ApiKeyAuth: []
components:
schemas:
Account:
type: object
description: The team behind the API key. Never contains a key value.
required:
- team
- billingMode
- plan
- credits
- storage
- keys
properties:
team:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
billingMode:
type: string
enum:
- managed
- byok
description: >-
`managed`: generation runs on Hooked's provider keys and is paid
with credits. `byok`: your team generates with its own provider keys
(Settings → AI keys) and no credits are taken.
plan:
type: object
required:
- name
- status
- renewsAt
properties:
name:
type: string
description: The plan, e.g. `free`, `starter`, `pro`, `premium`, `ultra`.
status:
type: string
description: >-
Subscription status: `active`, `trialing`, `past_due`,
`canceled`, `inactive`, …
renewsAt:
type: string
format: date-time
nullable: true
description: Next renewal, or `null` when the plan does not renew.
credits:
type: object
required:
- balance
- chargedForGeneration
properties:
balance:
type: number
description: 'Credits left: the plan''s plus any extra credits bought.'
chargedForGeneration:
type: boolean
description: >-
`true` on managed: creating a video spends from `balance`.
`false` on byok: the balance is not used for generation.
storage:
type: object
required:
- usedBytes
- limitBytes
properties:
usedBytes:
type: integer
description: Bytes your media library and videos take.
limitBytes:
type: integer
description: Your plan's storage limit, in bytes.
keys:
type: array
nullable: true
description: >-
byok only (`null` on managed): each provider and whether its key is
set and working. Never the key itself.
items:
type: object
required:
- provider
- configured
- status
properties:
provider:
type: string
description: e.g. `openrouter`, `elevenlabs`, `gemini`.
configured:
type: boolean
description: A key is saved for this provider.
status:
type: string
enum:
- ok
- missing
- invalid
description: >-
`ok`: validated and working. `missing`: none saved. `invalid`:
saved but it failed (fix it in Settings → AI keys).
Error401:
type: object
description: Missing or invalid `x-api-key`.
properties:
code:
type: string
enum:
- not_authenticated
message:
type: string
example: Not authenticated
errorCode:
type: string
enum:
- NOT_AUTHENTICATED
details:
type: object
additionalProperties:
type: string
example:
code: not_authenticated
message: Not authenticated
errorCode: NOT_AUTHENTICATED
details:
x-api-key: Header not provided or API Key invalid
EntitlementRequired403:
type: object
description: >-
Valid key, but the team does not have the product this endpoint belongs
to.
properties:
code:
type: string
enum:
- entitlement_required
error:
type: string
enum:
- entitlement_required
message:
type: string
product:
type: string
example: app
required:
- code
- error
- message
- product
example:
code: entitlement_required
error: entitlement_required
message: This endpoint requires the "app" product.
product: app
Error500:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
error:
type: string
description: Present on some endpoints
example:
success: false
message: Internal server error
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
EntitlementRequired:
description: The team does not have the product this endpoint needs
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequired403'
RateLimited429:
description: >-
Your team is over a rate limit: 30 POST requests per minute, 120 other
requests per minute, or 3 downloads of your URLs running at once.
Nothing ran and nothing was charged: wait `Retry-After` seconds and send
the request again. See [Rate
limits](/guides/error-handling#rate-limits-429).
headers:
Retry-After:
description: Seconds to wait before sending again.
schema:
type: integer
X-RateLimit-Limit:
description: The limit of the bucket you hit (not sent for the download cap).
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in this window: 0 (not sent for the download cap).'
schema:
type: integer
X-RateLimit-Reset:
description: >-
When the window ends, in Unix seconds (not sent for the download
cap).
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- RATE_LIMITED
message:
type: string
retryAfterSeconds:
type: integer
required:
- success
- errorCode
- message
- retryAfterSeconds
example:
success: false
errorCode: RATE_LIMITED
message: >-
Rate limit exceeded: 30 POST requests per minute per team. Retry
after 12 s.
retryAfterSeconds: 12
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.