> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fact0.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry client

> Go TelemetryClient for execution tracing, spans, and replay.

# Telemetry client

```go theme={null}
import (
    "os"
    fact0 "github.com/fact0-ai/fact0/sdk/go"
)

client := fact0.NewClient(fact0.Config{
    APIKey: os.Getenv("FACT0_API_KEY"),
})
tel := client.Telemetry
```

<Note>
  Telemetry requires the same `f0_live_*` API key as the audit log.
</Note>

## How it works

The execution DAG (Directed Acyclic Graph) is **reconstructed dynamically on the backend** from the trace relationships you stream. The SDK client doesn't need to manually compute the DAG tree; it simply starts the execution, records the spans (linking them to parent spans via `parent_span_id`), and ends the execution.

## Telemetry workflow

```go theme={null}
// 1. Start the execution
exec, err := tel.StartExecution(context.Background(), fact0.StartExecutionRequest{
    AgentID:   "customer-support-bot",
    AgentName: "Support Bot",
    Trigger:   "user_query",
})
if err != nil {
    log.Fatal(err)
}
executionID := exec["id"].(string)

// 2. Ingest spans with parent-child relationships
_, err = tel.IngestSpans(context.Background(), executionID, []map[string]interface{}{
    {
        "span_id":    "span-1",
        "span_type":  "TOOL_CALL",
        "name":       "Search Knowledge Base",
        "start_time": "2026-06-22T22:00:00Z",
        "end_time":   "2026-06-22T22:00:00.210Z",
        "tool_call": map[string]interface{}{
            "tool_name":   "knowledge_search",
            "duration_ms": 210,
            "input":       map[string]interface{}{"inline": map[string]interface{}{"query": "refund policy"}},
            "output":      map[string]interface{}{"inline": map[string]interface{}{"hits": 5}},
        },
    },
    {
        "span_id":        "span-2",
        "span_type":      "MODEL_INVOCATION",
        "name":           "Generate Answer",
        "parent_span_id": "span-1",
        "start_time":     "2026-06-22T22:00:00.210Z",
        "end_time":       "2026-06-22T22:00:01.450Z",
        "model_invocation": map[string]interface{}{
            "model_name":        "gpt-4o",
            "model_provider":    "openai",
            "prompt_tokens":     1200,
            "completion_tokens": 250,
            "total_tokens":      1450,
            "session_id":        "session_9a2f1b",
            "turn_sequence":     2,
            "prompt_name":       "customer-inquiry",
            "prompt_version":    3,
            "cost_usd":          0.00725,
        },
    },
})
if err != nil {
    log.Fatal(err)
}
```

## Read methods

| Method                            | REST                                 | Description                                |
| --------------------------------- | ------------------------------------ | ------------------------------------------ |
| `ListExecutions(ctx, query)`      | `GET /api/v1/executions`             | List agent runs and metadata               |
| `GetExecution(ctx, executionID)`  | `GET /api/v1/executions/{id}`        | Get run summary and state                  |
| `GetDAG(ctx, executionID)`        | `GET /api/v1/executions/{id}/dag`    | **Get the backend-computed execution DAG** |
| `Replay(ctx, executionID, query)` | `GET /api/v1/executions/{id}/replay` | Get visual step-by-step replay states      |

## Ingest methods

| Method                                   | REST                                  | Description                            |
| ---------------------------------------- | ------------------------------------- | -------------------------------------- |
| `StartExecution(ctx, req)`               | `POST /api/v1/executions`             | Registers a new agent execution        |
| `IngestSpans(ctx, executionID, spans)`   | `POST /api/v1/executions/{id}/spans`  | Stream execution spans to the backend  |
| `IngestEvents(ctx, executionID, events)` | `POST /api/v1/executions/{id}/events` | Stream execution events to the backend |
| `EndExecution(ctx, executionID, status)` | `PUT /api/v1/executions/{id}/end`     | Close the execution run                |

Status values: `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`.