telnyx 7.25.0 → 7.26.0

package/src/resources/llm-token-gateway/usage.ts

@@ -1,28 +1,36 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as UsageAPI from './usage';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
 /**
- * Manage and report AI Gateway traffic.
+ * Manage and report AI Gateway usage.
  */
 export class Usage extends APIResource {
   /**
-   * Return complete usage totals, UTC daily and model breakdowns, and guardrail
-   * event counts for one token group owned by the authenticated account. Requires
-   * the llm_token_gateway.usage.read permission; spend and guardrail read
-   * permissions do not grant this combined report. All sections share one database
-   * snapshot and include the latest usage corrections. Dates use an inclusive start
-   * and exclusive end spanning 1 to 31 days. Only token_group_id, start_date and
-   * end_date are accepted; pagination, group_by and other filters are rejected.
-   * Spend is reference/enforcement USD, not invoice truth or BYOK provider charges.
-   * Unknown cost is excluded from spend and reported through unknown_requests and
-   * reserved_spend. Daily rows include zero-activity days. Model rows are ordered by
-   * request count descending, then model name, and are limited to 1,000. Guardrail
-   * counts count events, not distinct requests; recent_events contains at most 20
-   * newest events. A report that exceeds model or query limits returns 503 rather
-   * than a truncated success.
+   * Gateway reference/enforcement usage, not invoice truth or BYOK provider charges.
+   * Requires the dedicated llm_token_gateway.usage.read V2 action for combined spend
+   * and guardrail reporting; existing spend.read and guardrail_events.read grants do
+   * not grant this endpoint. All totals, UTC daily buckets, models and latest 20
+   * guardrail events share one database snapshot. UTC half-open dates, at most 31
+   * days. Zero-filled days; at most 1000 models (503 rather than truncation on
+   * overflow/timeout). Known tokens sum independently known categories across latest
+   * attempt evidence, including corrections; unknown spend is excluded and
+   * unknown_requests/reserved_spend remain explicit. Guardrail counts count events,
+   * not distinct requests. No raw spend events, prompts or secrets. This read-only
+   * report creates no pagination snapshot and accepts no pagination parameters.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.llmTokenGateway.usage.retrieveSummary({
+   *     end_date: '2019-12-27',
+   *     start_date: '2019-12-27',
+   *     token_group_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   });
+   * ```
    */
   retrieveSummary(
     query: UsageRetrieveSummaryParams,
@@ -30,172 +38,288 @@ export class Usage extends APIResource {
   ): APIPromise<UsageRetrieveSummaryResponse> {
     return this._client.get('/llm_token_gateway/usage/summary', { query, ...options });
   }
+
+  /**
+   * Durable, replayable, content-free usage export for customer pipelines. Requires
+   * the dedicated llm_token_gateway.usage_export.read V2 action; spend.read and
+   * usage.read do not grant it. Records are inference.request (one per immutable
+   * ledger revision; a correction adds a new id with supersedes, keep the highest
+   * revision per request_id) and guardrail.evaluation (one per guardrail event,
+   * including blocked prompts with no inference record; correlate on request_id).
+   * Delivery is at least once in commit order: deduplicate on id. Records appear
+   * after settlement and after every older database transaction has finished
+   * (meta.horizon_lag_seconds); keep polling with next_cursor, which is always
+   * returned and is reusable after has_more is false. After a logical database
+   * restore, restart from start_time and deduplicate on id; a cursor from before it
+   * may return 409 cursor_expired (no Retry-After). Retention promise 30 days. No
+   * prompts, responses, provider credentials, supplier or customer rates. Gateway
+   * reference/enforcement usage, not invoice truth or BYOK provider charges.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.llmTokenGateway.usage.retrieveExport();
+   * ```
+   */
+  retrieveExport(
+    query: UsageRetrieveExportParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<UsageRetrieveExportResponse> {
+    return this._client.get('/llm_token_gateway/usage/export', { query, ...options });
+  }
 }
 
-export interface UsageRetrieveSummaryResponse {
-  data: UsageRetrieveSummaryResponse.Data;
+export interface GuardrailFinding {
+  action: 'flag' | 'block';
 
-  meta: UsageRetrieveSummaryResponse.Meta;
+  code: string;
+
+  count: number;
+
+  detector: 'secrets' | 'dlp' | 'safety';
 }
 
-export namespace UsageRetrieveSummaryResponse {
-  export interface Data {
+export interface UsageRetrieveExportResponse {
+  data: Array<
+    | UsageRetrieveExportResponse.UsageExportInferenceRequest
+    | UsageRetrieveExportResponse.UsageExportGuardrailEvaluation
+  >;
+
+  meta: UsageRetrieveExportResponse.Meta;
+}
+
+export namespace UsageRetrieveExportResponse {
+  export interface UsageExportInferenceRequest {
     /**
-     * One row per UTC day, including zero-activity days.
+     * Deterministic: req\_{request_id}\_r{revision}. Deduplicate on id.
      */
-    by_day: Array<Data.ByDay>;
+    id: string;
+
+    attempts: number;
+
+    biller: 'telnyx' | 'provider' | 'none';
+
+    cache_hit: boolean;
+
+    configuration_version: number;
 
     /**
-     * One row per model, ordered by request count descending then model name.
+     * USD decimal string with exactly 6 places, 0 to 1000000000.000000 (the Money
+     * bound); enforcement basis, not invoice truth.
      */
-    by_model: Array<Data.ByModel>;
+    cost: string | null;
+
+    end_user_id: string | null;
+
+    input_tokens: number | null;
 
     /**
-     * Complete guardrail event counts and bounded recent findings for the same group
-     * and range.
+     * Customer request tags captured at admission; {} when untagged.
      */
-    guardrails: Data.Guardrails;
+    metadata: { [key: string]: string | number | boolean };
+
+    model: string;
+
+    output_tokens: number | null;
+
+    protocol: 'openai' | 'anthropic';
+
+    provider: string;
+
+    provider_key_id: string | null;
+
+    provider_model: string;
+
+    rate_version: string;
+
+    request_id: string;
+
+    revision: number;
+
+    route_mode: 'managed' | 'byok' | 'cache';
+
+    schema_version: 1;
+
+    status: 'succeeded' | 'failed' | 'partial' | 'unknown';
+
+    stream: boolean;
 
     /**
-     * Metrics for all matching requests.
+     * Previous revision id; keep the highest revision per request_id.
      */
+    supersedes: string | null;
+
+    timings: UsageExportInferenceRequest.Timings;
+
+    token_group_id: string;
+
+    token_key_id: string;
+
+    token_user_id: string | null;
+
+    type: 'inference.request';
+
+    usage_source: 'provider' | 'gateway_tokenizer' | 'operator' | null;
+
+    usage_status: 'known' | 'unknown' | 'reconciled';
+  }
+
+  export namespace UsageExportInferenceRequest {
+    export interface Timings {
+      admitted_at: string;
+
+      completed_at: string | null;
+
+      first_attempt_at: string | null;
+
+      /**
+       * completed_at - admitted_at as recorded by the ledger; not time to first token.
+       */
+      gateway_duration_ms: number | null;
+
+      settled_at: string;
+    }
+  }
+
+  export interface UsageExportGuardrailEvaluation {
+    id: string;
+
+    created_at: string;
+
+    end_user_id: string | null;
+
+    evaluation_input_tokens: number | null;
+
+    evaluation_output_tokens: number | null;
+
+    findings: Array<UsageAPI.GuardrailFinding>;
+
+    /**
+     * Customer request tags from the x-ltg-metadata header: up to 5 entries. Keys are
+     * case-sensitive; keys starting with ltg*, telnyx*, litellm* or cf* (any case) are
+     * reserved. Values are strings (1-256 characters, no control or format
+     * characters), integers within +/-9007199254740991, or booleans; floats, null,
+     * objects and arrays are rejected. Values that look like credentials are rejected.
+     * Tags are attribution only: never forwarded upstream, never part of the response
+     * cache key, never used for budgets or routing. An untagged request reports {}.
+     */
+    metadata: { [key: string]: string | number | boolean };
+
+    model: string;
+
+    outcome: 'evaluated' | 'flagged' | 'blocked' | 'unevaluated';
+
+    request_id: string;
+
+    schema_version: 1;
+
+    stage: 'prompt' | 'response';
+
+    token_group_id: string;
+
+    token_key_id: string;
+
+    token_user_id: string | null;
+
+    type: 'guardrail.evaluation';
+  }
+
+  export interface Meta {
+    has_more: boolean;
+
+    horizon_lag_seconds: number;
+
+    next_cursor: string;
+  }
+}
+
+export interface UsageRetrieveSummaryResponse {
+  data: UsageRetrieveSummaryResponse.Data;
+
+  meta: UsageRetrieveSummaryResponse.Meta;
+}
+
+export namespace UsageRetrieveSummaryResponse {
+  export interface Data {
+    by_day: Array<Data.ByDay>;
+
+    by_model: Array<Data.ByModel>;
+
+    guardrails: Data.Guardrails;
+
     totals: Data.Totals;
   }
 
   export namespace Data {
     export interface ByDay {
-      /**
-       * Requests served from the gateway cache.
-       */
       cache_hits: number;
 
-      /**
-       * UTC day.
-       */
       date: string;
 
-      /**
-       * Requests classified as failed.
-       */
       failed_requests: number;
 
-      /**
-       * Independently known input tokens across attempts, including corrected usage.
-       */
       input_tokens: number;
 
-      /**
-       * Independently known output tokens across attempts, including corrected usage.
-       */
       output_tokens: number;
 
-      /**
-       * Requests classified as partial after streaming began.
-       */
       partial_requests: number;
 
-      /**
-       * Number of matching requests.
-       */
       requests: number;
 
       /**
-       * Unresolved budget reservations in USD.
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
        */
       reserved_spend: number;
 
       /**
-       * Sum of known reference/enforcement cost in USD.
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
        */
       spend: number;
 
-      /**
-       * Requests classified as succeeded.
-       */
       succeeded_requests: number;
 
-      /**
-       * Requests whose cost remains unresolved; unknown cost is excluded from spend.
-       */
       unknown_requests: number;
     }
 
     export interface ByModel {
-      /**
-       * Requests served from the gateway cache.
-       */
       cache_hits: number;
 
-      /**
-       * Requests classified as failed.
-       */
       failed_requests: number;
 
-      /**
-       * Independently known input tokens across attempts, including corrected usage.
-       */
       input_tokens: number;
 
-      /**
-       * Model identifier.
-       */
       model: string;
 
-      /**
-       * Independently known output tokens across attempts, including corrected usage.
-       */
       output_tokens: number;
 
-      /**
-       * Requests classified as partial after streaming began.
-       */
       partial_requests: number;
 
-      /**
-       * Number of matching requests.
-       */
       requests: number;
 
       /**
-       * Unresolved budget reservations in USD.
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
        */
       reserved_spend: number;
 
       /**
-       * Sum of known reference/enforcement cost in USD.
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
        */
       spend: number;
 
-      /**
-       * Requests classified as succeeded.
-       */
       succeeded_requests: number;
 
-      /**
-       * Requests whose cost remains unresolved; unknown cost is excluded from spend.
-       */
       unknown_requests: number;
     }
 
-    /**
-     * Complete guardrail event counts and bounded recent findings for the same group
-     * and range.
-     */
     export interface Guardrails {
-      /**
-       * Total blocked guardrail events, not distinct requests.
-       */
       blocked_events: number;
 
-      /**
-       * Total flagged guardrail events, not distinct requests.
-       */
       flagged_events: number;
 
-      /**
-       * Up to 20 newest privacy-safe guardrail events, ordered by creation time
-       * descending and event ID.
-       */
       recent_events: Array<Guardrails.RecentEvent>;
     }
 
@@ -211,11 +335,19 @@ export namespace UsageRetrieveSummaryResponse {
 
         evaluation_output_tokens: number | null;
 
-        findings: Array<RecentEvent.Finding>;
+        findings: Array<UsageAPI.GuardrailFinding>;
 
         /**
-         * Model identifier.
+         * Customer request tags from the x-ltg-metadata header: up to 5 entries. Keys are
+         * case-sensitive; keys starting with ltg*, telnyx*, litellm* or cf* (any case) are
+         * reserved. Values are strings (1-256 characters, no control or format
+         * characters), integers within +/-9007199254740991, or booleans; floats, null,
+         * objects and arrays are rejected. Values that look like credentials are rejected.
+         * Tags are attribution only: never forwarded upstream, never part of the response
+         * cache key, never used for budgets or routing. An untagged request reports {}.
          */
+        metadata: { [key: string]: string | number | boolean };
+
         model: string;
 
         outcome: 'evaluated' | 'flagged' | 'blocked' | 'unevaluated';
@@ -232,72 +364,35 @@ export namespace UsageRetrieveSummaryResponse {
 
         token_user_id: string | null;
       }
-
-      export namespace RecentEvent {
-        export interface Finding {
-          action: 'flag' | 'block';
-
-          code: string;
-
-          count: number;
-
-          detector: 'secrets' | 'dlp' | 'safety';
-        }
-      }
     }
 
-    /**
-     * Metrics for all matching requests.
-     */
     export interface Totals {
-      /**
-       * Requests served from the gateway cache.
-       */
       cache_hits: number;
 
-      /**
-       * Requests classified as failed.
-       */
       failed_requests: number;
 
-      /**
-       * Independently known input tokens across attempts, including corrected usage.
-       */
       input_tokens: number;
 
-      /**
-       * Independently known output tokens across attempts, including corrected usage.
-       */
       output_tokens: number;
 
-      /**
-       * Requests classified as partial after streaming began.
-       */
       partial_requests: number;
 
-      /**
-       * Number of matching requests.
-       */
       requests: number;
 
       /**
-       * Unresolved budget reservations in USD.
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
        */
       reserved_spend: number;
 
       /**
-       * Sum of known reference/enforcement cost in USD.
+       * USD, decimal precision at most 6 places; parse exactly to integer micro-USD,
+       * never binary float accounting.
        */
       spend: number;
 
-      /**
-       * Requests classified as succeeded.
-       */
       succeeded_requests: number;
 
-      /**
-       * Requests whose cost remains unresolved; unknown cost is excluded from spend.
-       */
       unknown_requests: number;
     }
   }
@@ -305,6 +400,11 @@ export namespace UsageRetrieveSummaryResponse {
   export interface Meta {
     end_date: string;
 
+    /**
+     * The metadata[<key>] filters applied to every section; {} when unfiltered.
+     */
+    metadata: { [key: string]: string };
+
     start_date: string;
 
     token_group_id: string;
@@ -312,25 +412,49 @@ export namespace UsageRetrieveSummaryResponse {
 }
 
 export interface UsageRetrieveSummaryParams {
+  end_date: string;
+
+  start_date: string;
+
+  token_group_id: string;
+
   /**
-   * Exclusive UTC date in YYYY-MM-DD format. Must follow start_date by 1 to 31 days.
+   * Request tag filters as metadata[<key>]=<value>, 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.
    */
-  end_date: string;
+  metadata?: { [key: string]: string };
+}
 
+export interface UsageRetrieveExportParams {
   /**
-   * Inclusive UTC date in YYYY-MM-DD format. Must precede end_date by 1 to 31 days.
+   * Opaque next_cursor from a previous page; not combinable with start_time. Bound
+   * to the requested types; the account always comes from the credential.
    */
-  start_date: string;
+  cursor?: string;
+
+  limit?: number;
 
   /**
-   * ID of a token group owned by the authenticated account.
+   * First page only: RFC 3339 with offset, at most 30 days ago and not in the
+   * future; default now - 24h.
    */
-  token_group_id: string;
+  start_time?: string;
+
+  /**
+   * Comma-separated subset of inference.request,guardrail.evaluation; default both.
+   */
+  types?: string;
 }
 
 export declare namespace Usage {
   export {
+    type GuardrailFinding as GuardrailFinding,
+    type UsageRetrieveExportResponse as UsageRetrieveExportResponse,
     type UsageRetrieveSummaryResponse as UsageRetrieveSummaryResponse,
     type UsageRetrieveSummaryParams as UsageRetrieveSummaryParams,
+    type UsageRetrieveExportParams as UsageRetrieveExportParams,
   };
 }

package/src/resources/phone-numbers/jobs.ts

@@ -15,9 +15,10 @@ import { path } from '../../internal/utils/path';
 export class Jobs extends APIResource {
   /**
    * Returns background jobs that operate on phone numbers. Filter by job type,
-   * target phone numbers, or job status, and sort by creation time. Multiple
-   * phone-number or status values use OR semantics within that filter; different
-   * filter categories use AND semantics. Results include pagination metadata.
+   * target phone numbers, job status, or creation-time customer reference, and sort
+   * by creation time. Multiple phone-number or status values use OR semantics within
+   * that filter; different filter categories use AND semantics. Results include
+   * pagination metadata.
    *
    * @example
    * ```ts
@@ -242,7 +243,8 @@ export interface JobUpdateEmergencySettingsBatchResponse {
 export interface JobListParams extends DefaultFlatPaginationParams {
   /**
    * Consolidated filter parameter (deepObject style). Originally: filter[type],
-   * filter[phone_number], filter[phone_number][], filter[status][]
+   * filter[phone_number], filter[phone_number][], filter[status][],
+   * filter[customer_reference]
    */
   filter?: JobListParams.Filter;
 
@@ -256,9 +258,20 @@ export interface JobListParams extends DefaultFlatPaginationParams {
 export namespace JobListParams {
   /**
    * Consolidated filter parameter (deepObject style). Originally: filter[type],
-   * filter[phone_number], filter[phone_number][], filter[status][]
+   * filter[phone_number], filter[phone_number][], filter[status][],
+   * filter[customer_reference]
    */
   export interface Filter {
+    /**
+     * Returns jobs whose creation-time customer reference exactly matches the supplied
+     * value, not the current reference on a phone number. Only jobs within the lookup
+     * window (90 days by default) are returned. Supply a single non-blank string of up
+     * to 250 characters, without null characters, using
+     * `filter[customer_reference]=yourcustomerrefhere`. An invalid filter value
+     * returns HTTP 422.
+     */
+    customer_reference?: string;
+
     /**
      * Returns jobs that targeted any of the supplied account-owned phone numbers.
      * Values beginning with `+` must contain 1 to 20 digits after the plus sign. The

package/src/resources/reputation/numbers.ts

@@ -59,6 +59,13 @@ export interface NumberListParams extends DefaultFlatPaginationParams {
    */
   'filter[enterprise_id]'?: string;
 
+  /**
+   * Only numbers with this ownership status. `removed` lists the numbers that were
+   * removed, each with its `removal_reason` and `removed_at`; removed numbers are
+   * not returned otherwise.
+   */
+  'filter[ownership_status]'?: ReputationNumbersAPI.ReputationOwnershipStatus;
+
   /**
    * Partial match on phone number. Must contain at least 5 digits.
    */
@@ -68,6 +75,11 @@ export interface NumberListParams extends DefaultFlatPaginationParams {
    * Exact phone-number match (E.164).
    */
   'filter[phone_number][eq]'?: string;
+
+  /**
+   * Only numbers with this source.
+   */
+  'filter[source]'?: ReputationNumbersAPI.ReputationNumberSource;
 }
 
 export interface NumberRetrieveParams {