List gateway spend events

Return request-level usage history for the authenticated account. Supply both UTC dates or neither; omitting both returns the previous full UTC day. 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

events

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.retrieveEvents();

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_events()
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.GetEvents(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().retrieveEvents();
    }
}

<?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->retrieveEvents();

  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"
  }
}

{
  "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>

end_date

string<date>

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

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.retrieveEvents();

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_events()
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.GetEvents(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().retrieveEvents();
    }
}

<?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->retrieveEvents();

  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"
  }
}

{
  "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

List gateway spend events

Authorizations

Query Parameters

Response