API Access to Logs - TrueFoundry Docs

The LLM Gateway delivers detailed request logs through tracing. Retrieve these logs using the Query Spans API.

To better understand tracing concepts like traces, spans, and how they work together, see our tracing overview.

Section	Description
Overview	Quickstart with SDK and HTTP API
Trace inspection	Inspect a single trace and span hierarchy
Filtering	Filter request logs
Basic queries	Time range, users, virtual accounts
Advanced queries	Trace ID, model spans, metadata, MCP
Span attributes	Attribute reference

Quickstart

Using TrueFoundry SDK
Using HTTP API

Setup the TrueFoundry SDK

To start querying request logs, install and configure the TrueFoundry SDK and CLI.
Follow the CLI Setup Guide for installation instructions and authentication steps.Once setup is complete, you can use the SDK to query tracing data programmatically.

Fetch using TrueFoundry SDK

Each request to the LLM Gateway generates a traceâ€”a timeline of everything that happened, from the incoming request to guardrails to the model call and any external APIs. Let’s pull the latest Gateway traces and see real data quickly.Fetch the latest LLM Gateway request logs:

You can get the tracing_project_fqn from the Fetch via API button on the Request Logs page

from truefoundry import client

# Fetch LLM Gateway request logs
spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-01-21T00:00:00.000Z",
)

for span in spans:
    print(span.span_name, span.span_attributes.get('tfy.span_type'))

Authentication

To start querying request logs, you need to authenticate with your TrueFoundry API key. You can use either a Personal Access Token (PAT) or Virtual Account Token (VAT).

Get your API key

To generate an API key:

Personal Access Token (PAT): Go to Access â†’ Personal Access Tokens in your TrueFoundry dashboard
Virtual Account Token (VAT): Go to Access â†’ Virtual Account Tokens (requires admin permissions)

For detailed authentication setup, see our Authentication guide.

Fetch using HTTP API

You can get the tracing_project_fqn from the Fetch via API button on the Request Logs page

import requests

page_token = None
done = False
while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T20:16:54",
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['spanAttributes'].get('tfy.span_type', ''))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch spans completed!")

Request Logs: Trace Inspection

Inspect a single Gateway trace and understand span hierarchy

Request Logs: Filtering

Filter Gateway request logs by time, user, trace ID, and more

Request Logs: Span Attributes

Reference for span attributes captured in AI Gateway request logs, including model, token usage, and request metadata fields.

Use Cases

Request Logs: Common Use Cases

Common span query patterns for time ranges, users, and virtual accounts

Request Logs: Advanced Queries

Filter by trace ID, model spans, metadata, and MCP

API Access to MCP Metrics Overview

⌘I

​Contents

​Quickstart

​Setup the TrueFoundry SDK

​Fetch using TrueFoundry SDK

​Authentication

​Fetch using HTTP API

Use Cases

Contents

Quickstart

Setup the TrueFoundry SDK

Fetch using TrueFoundry SDK

Authentication

Fetch using HTTP API