Skills Billing and Quotas
Skills billing is based on durable usage records. Limits are checked before
expensive synthesis, validation, shared-library reuse, hosted-session action
execution, or invocation starts. Public responses use typed errors with stable
fields, so clients should branch on error and details.category rather than
message text.
Billable Operation Classes
| Operation class | Metered unit | What counts | Notes |
|---|---|---|---|
| Private generation | skill_generations | A synthesis execution for a private generated skill. | This is the baseline generation class. |
| Learning-enabled generation | skill_generations | A synthesis execution where the account has approved learning consent and the request supplies the required learning signal. | This class uses the approved learning discount and may become eligible for a reusable-skill credit. |
| Validation | skill_validations | A validation attempt against a generated or candidate version. | Failed validation still consumes a validation attempt because protected execution work ran. |
| Invocation | skill_invocations | A public skill invocation through the protected execution boundary. | The quota check happens before boundary execution starts. |
| Hosted-session action execution | skill_invocations | A hosted-session action backed by an approved shared skill. | Hosted sessions use the same invocation quota dimension. |
| Library reuse | skill_library_reuses | Selection or execution of an approved visible shared-library skill instead of new generation. | Reuse is lower cost than generation and should be tried before synthesis. |
| Reusable-skill credit application | skill_generations adjustment | A durable credit_applied adjustment for an accepted net-new reusable skill. | Credits are explicit accounting records, not log-derived claims. |
Usage records do not include prompts, generated source, validation payloads, connector credentials, private tenant payloads, private outputs, or raw worker errors.
Default Quotas
Account plans can override quota values, but the default Skills quota dimensions are:
| Dimension | Default monthly limit |
|---|---|
skill_generations | 25 |
skill_validations | 50 |
skill_invocations | 500 |
skill_library_reuses | 500 |
Quota windows and plan overrides are account state. API clients should treat the
values in a quota_exceeded response as authoritative for that request rather
than hardcoding these defaults.
Learning-Enabled Generation
Learning-enabled generation is a discounted generation path for accounts that have approved the required learning terms. A request must select the learning-enabled billing mode and supply the public-safe learning signal required by the API schema. Missing, expired, or revoked consent fails before reuse preflight, generation quota checks, or job creation.
Learning-enabled generation does not publish private customer work. Candidate promotion still requires evaluation for privacy, novelty, safety, library-gap fit, duplicate risk, provenance, and curation readiness.
Reusable-Skill Credits
An accepted net-new reusable skill can produce a pending reusable-skill credit
when the candidate is creditable and fills a measured library gap. The credit is
not applied from telemetry, logs, or inferred success. The settlement path reads
durable accepted or curation-ready credit states and writes an explicit
credit_applied adjustment.
If generation is blocked by quota while unapplied reusable-skill credits exist,
the public API can return credit_pending. Treat that as a billing-state
condition: wait for settlement, refresh account usage, or contact support if
the pending state does not clear.
Typed Limit And Billing Errors
| Error | Category | HTTP status | Retry | Developer action |
|---|---|---|---|---|
quota_exceeded | quota | 429 | No | Show the quota dimension, current value, limit, and reset window from details. Reuse an approved library skill or wait for quota reset. |
credit_pending | billing | 409 | Later | Refresh account usage after settlement or wait for the pending reusable-skill credit to apply. |
billing_required | billing | 402 | No | Ask the account owner to resolve billing, upgrade, or remove the spend cap. |
billing_unavailable | billing | 503 | Yes | Retry with bounded backoff because quota or credit state could not be read. |
learning_consent_required | learning | 403 | No | Ask the account owner to approve learning terms or switch to private generation. |