Usage and billing
How Hull Gateway usage is measured and billed, what happens when you run out, and the controls organizations get.
Hull Gateway records the tokens and cost of every request and counts paid usage against your Hull plan. You can see your usage in the Hull dashboard.
Plans
| Plan | AI usage |
|---|---|
| Free | Limited managed AI for evaluation |
| Starter | Monthly AI allowance, Auto routing through Hull Gateway, usage tracking and spending controls |
| Pro | Higher monthly AI allowance with transparent overages |
| Teams | Pooled organization allowance, centralized billing and usage visibility, organization spending controls |
| Enterprise | Managed Hull Gateway with model policies, Enterprise BYOK and custom usage budgets |
How allowances work:
- Paid individual plans include a monthly AI allowance. Teams shares a pooled allowance across the organization.
- Allowances reset each billing period and don't roll over.
- Once you've used your allowance, you can buy additional usage.
- AI usage isn't unlimited.
See pricing for current prices.
How a request is billed
- Check. Before sending a request to a paid model, Hull Gateway checks that you (or your organization) have usage available.
- Run. The request goes to the model provider.
- Measure. Hull Gateway reads token counts and cost from the provider's response.
- Record. The cost is recorded against your account or organization.
Cost is based on the model provider's pricing for:
- Input tokens: your prompt, including system messages and tool definitions.
- Output tokens: what the model generates, including reasoning.
- Cache writes: tokens written to the provider's prompt cache.
- Cache reads: tokens served from the provider's prompt cache, usually discounted.
Token counts come from the provider's own tokenizer. Hull Gateway doesn't re-tokenize.
Free models and BYOK
- Free models have no cost. Usage is recorded but not billed.
- BYOK requests are billed by the provider on your own account and don't count against your Hull allowance.
When you run out
If you don't have usage available for a paid model, the request returns HTTP 402 with error_type: "usage_limit_exceeded" and a link to add usage. Free models keep working, subject to their rate limits.
If an automatic top-up is still processing, you may get a short-lived error asking you to retry in a few seconds.
Organization controls
Organizations draw from a shared pool and can control how members use it.
- Shared usage: members' requests count against the organization, not their personal accounts. Send the
X-HullCode-OrganizationIdheader from your own code. - Per-member daily limits: cap how much each member can spend per day. When a member reaches the limit, further paid requests are refused until the next day.
- Model and provider policies (Enterprise): allow or deny specific models and restrict which providers can serve requests. Requests for a blocked model are rejected.
- Data collection policy: choose whether requests may go to providers that collect prompt data. Some free models require it to be allowed.
See Cost controls and Model access controls.
Rate limits
Hull Gateway applies rate limits per account, and free models have their own, stricter limits. When you're rate limited, you get HTTP 429. Model providers can also rate limit requests.
Usage data
For each request Hull records:
| Field | Description |
|---|---|
| Model | The model ID requested and the model that served it |
| Provider | The provider that served the request |
| Input and output tokens | Prompt and completion token counts |
| Cache tokens | Tokens written to and read from the prompt cache |
| Cost | The request's cost |
| Time to first token | Latency for streamed requests |
| BYOK | Whether your own provider key was used |
Your application also gets token usage in each response:
- Non-streaming: in the
usagefield of the response body. - Streaming: in the final chunk before
[DONE].