Create gateway token group

Create gateway token group within the authenticated Telnyx account. Foreign and unknown resource IDs return the same 404 response.

POST /llm_token_gateway/token_groups

JavaScript

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const TokenGroup = await client.llmTokenGateway.tokenGroups.create({
  allowed_models: [],
  name: 'name',
  'Idempotency-Key': 'idempotency-key',
});

console.log(TokenGroup.data);

201

{
  "data": {
    "record_type": "token_group",
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-10-07T08:00:00Z",
    "updated_at": "2026-10-07T08:00:00Z",
    "version": 1,
    "name": "support-backend",
    "max_budget": null,
    "budget_duration": "1d",
    "tpm_limit": null,
    "rpm_limit": null,
    "allowed_models": [
      "Kimi-K3",
      "GLM-5.3-Flash"
    ],
    "cache_ttl": null,
    "provider_key_ids": [],
    "guardrails": null,
    "fallbacks": null,
    "retries": null,
    "blocked": false,
    "spend": 0,
    "reserved_spend": 0,
    "budget_started_at": null,
    "resets_at": null,
    "max_parallel_requests": 20
  }
}

Authorizations

Authorization · string · header · required

Management-only Telnyx account credential.

Headers

Idempotency-Key · string · required

24h, scoped by account+method+path. Same key/body returns same outcome; changed body 409; in-progress 409 with Retry-After. Token-create replay returns 200 metadata WITHOUT secret.

Required string length: 1 - 128

Pattern: ^[A-Za-z0-9_-]+$

Body

application/json

name · string · required

Required string length: 1 - 256

Pattern: ^[^\u0000-\u001f\u007f]+$

allowed_models · string[] · required

Maximum array length: 1000

Required string length: 1 - 256

Pattern: ^[^\u0000-\u001f\u007f]+$

max_budget · number | null

USD, decimal precision at most 6 places; parse exactly to integer micro-USD, never binary float accounting.

Required range: 0 <= x <= 1000000000Must be a multiple of 0.000001

budget_duration · enum<string> | null

Available options: 1d, 7d, 30d, null

tpm_limit · integer | null

Required range: x >= 0

rpm_limit · integer | null

Required range: x >= 0

max_parallel_requests · integer | null

Optional maximum concurrent reserved/dispatched cache misses across replicas. Null means no concurrency cap. Cache hits do not consume slots; unknown usage retains its budget hold without a slot.

Required range: 1 <= x <= 1000

cache_ttl · integer | null

Required range: 1 <= x <= 86400

provider_key_ids · string<uuid>[]

Maximum array length: 1000

guardrails · object | null

Per-group guardrail policy. Missing actions default to ignore. profiles may be listed with both dlp actions ignore (staged, inactive) but a non-ignore dlp action requires at least one profile. streaming defaults to buffered when any response action is block and passthrough otherwise; passthrough with a response block is 400. Findings are codes and counts only; content is never stored. The stored form is echoed back canonicalised (all actions explicit, profiles sorted); {} is stored as an all-ignore policy, null disables.

Show child attributes

fallbacks · object | null

Per-group model fallbacks: primary alias -> ordered list of 1..3 other aliases. Every key and listed alias must be in allowed_models (a PATCH removing a referenced alias is 400); a chain never lists its own key; wildcards are rejected. Chains are one level deep (a step's own chain is not expanded). Fallback is attempted only for managed routes, only before the first provider event is forwarded, and only to steps the key may use; each attempt is reserved and recorded. {} and null both disable fallbacks.

Show child attributes

retries · object | null

Per-group same-route retries. max_attempts counts the first try of each step (the primary and each fallback) and is the ceiling for the x-ltg-max-attempts request header. A step is retried only when its attempt definitely did no provider work (connection failure before dispatch, or 429/529) before the first provider event; an uncertain failure (timeout, 408/500/502/503/504) moves to the next fallback step instead. max_attempts x (1 + the longest fallback chain) must not exceed 8, else 400. The n-th retry waits retry_delay_ms (constant), retry_delay_msn (linear) or retry_delay_ms2^(n-1) (exponential), at most 5 s and never past the request deadline, then jittered uniformly down to half that value so concurrent retries spread out; a provider Retry-After of at most 5 s is honoured and a longer one moves to the next step. request_timeout_ms applies to streaming requests only: it bounds each attempt's time to its first provider event and never applies after it. Non-stream requests keep the per-attempt hop and idle bounds (their headers arrive only with the finished completion). retry_delay_ms and backoff are floors for the request knobs. Each planned attempt is reserved (at most 8 per request); unused reservation is released at settlement. Managed routes only. The stored form is echoed back with defaults filled in; null disables retries.

Show child attributes

blocked · boolean

Response

201

application/json

OK

data · object · required

Show child attributes