Get gateway spend summary

Return request counts, token counts and reference spend grouped by one attribution dimension. Both UTC dates and group_by are required. Dates use a half-open range [start_date, end_date) of at most 31 days. Cost reflects budget reference rates, not invoice charges. Unknown spend is excluded and reported separately. The report snapshot supports at most 10,000 matching requests, independently of page size. Exceeding this bound returns HTTP 503 without partial results. Narrow the date range or resource filters before retrying. A failed report must not be interpreted as zero usage. Request tags can filter either report and metadata:<key> can group the summary.

GET

llm_token_gateway

spend

summary

JavaScript

import Telnyx from 'telnyx';

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

const response = await client.llmTokenGateway.spend.retrieveSummary();

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.llm_token_gateway.spend.retrieve_summary()
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.LlmTokenGateway.Spend.GetSummary(context.TODO())
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var response = client.llmTokenGateway().spend().retrieveSummary();
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->llmTokenGateway->spend->retrieveSummary();

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "data": [],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "has_more": false,
    "snapshot": "9b7e4a10-3c2d-4f5e-8a6b-1d2c3e4f5a60",
    "start_date": "2026-09-01",
    "end_date": "2026-09-08",
    "group_by": "token_group"
  }
}

{
  "errors": [
    {
      "code": "invalid_request",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "unauthorized",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "unauthorized",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "not_found",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "conflict",
      "title": "Snapshot conflict",
      "detail": "Correct the parameters to match a valid snapshot, or restart at page[number]=1 without page[snapshot].",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "precondition_failed",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "precondition_required",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "rate_limit_exceeded",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "invalid_request",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "enforcement_unavailable",
      "title": "Request could not be completed",
      "detail": "The report is unavailable or exceeds 10,000 matching requests. Narrow the date range or resource filters if the capacity limit is exceeded.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "invalid_request",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Management-only Telnyx account credential.

Query Parameters

page[number]

integer

default:1

Required range: x >= 1

page[size]

integer

default:20

Required range: 1 <= x <= 100

page[snapshot]

string

Required after page 1; account/filter-bound 15-minute stable snapshot; expired/mismatch 409.

Required string length: 1 - 256

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

start_date

string<date>

required

end_date

string<date>

required

token_group_id

string<uuid>

token_user_id

string<uuid>

token_key_id

string<uuid>

end_user_id

string

Required string length: 1 - 256

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

metadata

object

Request tag filters as metadata[]=, at most 5, combined with AND. A value matches the tag's text form exactly (booleans as true/false, integers in decimal), so metadata[flag]=true matches both boolean true and the string "true". Keys are case-sensitive; reserved-prefix keys are rejected. Unindexed: bounded by the account, the date range and the report timeout.

Show child attributes

group_by

required

A scope, or metadata: to group by one request tag's text-form value; requests without the key form one group with a null dimension_id.

Available options:

token_group,

token_user,

token_key,

end_user

Response

data

object[]

required

Show child attributes

meta

object

required

Show child attributes

JavaScript

import Telnyx from 'telnyx';

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

const response = await client.llmTokenGateway.spend.retrieveSummary();

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.llm_token_gateway.spend.retrieve_summary()
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.LlmTokenGateway.Spend.GetSummary(context.TODO())
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var response = client.llmTokenGateway().spend().retrieveSummary();
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->llmTokenGateway->spend->retrieveSummary();

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "data": [],
  "meta": {
    "page_number": 1,
    "page_size": 20,
    "has_more": false,
    "snapshot": "9b7e4a10-3c2d-4f5e-8a6b-1d2c3e4f5a60",
    "start_date": "2026-09-01",
    "end_date": "2026-09-08",
    "group_by": "token_group"
  }
}

{
  "errors": [
    {
      "code": "invalid_request",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "unauthorized",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "unauthorized",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "not_found",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "conflict",
      "title": "Snapshot conflict",
      "detail": "Correct the parameters to match a valid snapshot, or restart at page[number]=1 without page[snapshot].",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "precondition_failed",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "precondition_required",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "rate_limit_exceeded",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "invalid_request",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "enforcement_unavailable",
      "title": "Request could not be completed",
      "detail": "The report is unavailable or exceeds 10,000 matching requests. Narrow the date range or resource filters if the capacity limit is exceeded.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "invalid_request",
      "title": "Request could not be completed",
      "detail": "Check the request and the documented handling for this error.",
      "meta": {
        "request_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

AI Gateway

API

Concepts

For AI Agents

Get gateway spend summary

Authorizations

Query Parameters

Response