# API Reference

Complete method signatures with type annotations. All methods are on the `AmplitudeAI` instance unless otherwise noted.

All tracking methods return a `message_id` or `invocation_id` (UUID string) that uniquely identifies the event. Use this ID to link scores via `score(target_id=...)` and tool calls via `track_tool_call(parent_message_id=...)`.

## Message Tracking

```python
ai.track_user_message(
    user_id: str,
    content: str,
    session_id: str,
    trace_id: str = None,                        # Groups related events within a session
    turn_id: int = None,                         # Auto-incremented if omitted
    message_id: str = None,                      # Custom ID; auto-generated UUID if omitted
    agent_id: str = None,
    parent_agent_id: str = None,                 # Delegating agent (multi-agent orchestration)
    customer_org_id: str = None,                 # End-customer org (multi-tenant platforms)
    env: str = None,                             # e.g., "production", "staging"
    agent_version: str = None,                   # e.g., "v4.2", "2025-02-11", git SHA
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,                        # Arbitrary key-value pairs stamped on every event (JSON)
    # Implicit feedback
    is_regeneration: bool = False,               # User requested regeneration
    is_edit: bool = False,                       # User edited a previous message
    edited_message_id: str = None,               # message_id of the original message that was edited
    # Attachments
    attachments: list[dict] = None,              # File metadata (type, name, size_bytes, mime_type, etc.)
    event_properties: dict = None,               # Additional custom event properties
    groups: dict = None,                         # B2B group properties
) -> str                                         # Returns message_id

ai.track_ai_message(
    user_id: str,
    content: str,
    session_id: str,
    model: str,                                  # e.g., "gpt-4o", "claude-3-sonnet"
    provider: str,                               # e.g., "openai", "anthropic"
    latency_ms: float,
    input_tokens: int = None,
    output_tokens: int = None,
    reasoning_tokens: int = None,                # Reasoning/thinking token count
    cache_read_tokens: int = None,               # Prompt cache read token count
    cache_creation_tokens: int = None,           # Prompt cache creation token count
    total_tokens: int = None,                    # Total token count (enrichment pipeline)
    total_cost_usd: float = None,                # Auto-calculated with cache-aware pricing if omitted
    finish_reason: str = None,
    tool_calls: list = None,
    reasoning_content: str = None,               # Reasoning/thinking text (respects content_mode)
    tool_definitions: list[dict] = None,         # Tool schemas sent to the LLM (respects content_mode)
    # Model configuration
    system_prompt: str = None,                   # System/developer message (respects content_mode)
    temperature: float = None,                   # Sampling temperature
    max_output_tokens: int = None,               # Max output token limit
    top_p: float = None,                         # Nucleus sampling parameter
    is_streaming: bool = None,                   # Whether response was streamed
    prompt_id: str = None,                       # Prompt version/template ID for A/B testing
    # Implicit feedback
    was_copied: bool = False,                    # User copied this response
    was_cached: bool = False,                    # Semantic cache hit (distinct from token-level prompt caching)
    model_tier: str = None,                      # Model tier override (auto-inferred from model name if omitted)
    attachments: list[dict] = None,              # AI-generated images, charts, files, etc.
    trace_id: str = None,                        # Groups related events within a session
    turn_id: int = None,
    message_id: str = None,                      # Custom ID; auto-generated UUID if omitted
    agent_id: str = None,
    parent_agent_id: str = None,                 # Delegating agent (multi-agent orchestration)
    customer_org_id: str = None,                 # End-customer org (multi-tenant platforms)
    env: str = None,                             # e.g., "production", "staging"
    agent_version: str = None,                   # e.g., "v4.2", "2025-02-11", git SHA
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,                        # Arbitrary key-value pairs stamped on every event (JSON)
    is_error: bool = False,                      # Whether the response represents an error
    error_message: str = None,                   # Error description when is_error=True
    ttfb_ms: float = None,                       # Time-to-first-byte in milliseconds
    event_properties: dict = None,               # Additional custom event properties
    groups: dict = None,
) -> str                                         # Returns message_id
```

## Operation Tracking

```python
ai.track_tool_call(
    user_id: str,
    tool_name: str,
    latency_ms: float,
    success: bool,
    session_id: str = None,
    trace_id: str = None,                        # Groups related events within a session
    turn_id: int = None,                         # Associates with a conversation turn
    invocation_id: str = None,                   # Custom ID; auto-generated UUID if omitted
    input: dict = None,                          # Respects content_mode
    output: Any = None,                          # Respects content_mode
    parent_message_id: str = None,               # message_id from track_ai_message()
    agent_id: str = None,
    parent_agent_id: str = None,                 # Delegating agent (multi-agent orchestration)
    customer_org_id: str = None,                 # End-customer org (multi-tenant platforms)
    env: str = None,                             # e.g., "production", "staging"
    agent_version: str = None,                   # e.g., "v4.2", "2025-02-11", git SHA
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,                        # Arbitrary key-value pairs stamped on every event (JSON)
    error_message: str = None,                   # Error description when success=False
    event_properties: dict = None,               # Additional custom event properties
    groups: dict = None,                         # B2B group properties
) -> str                                         # Returns invocation_id

ai.track_embedding(
    user_id: str,
    model: str,                                  # e.g., "text-embedding-3-small"
    provider: str,
    latency_ms: float,
    input_tokens: int = None,
    dimensions: int = None,                      # e.g., 1536, 3072
    total_cost_usd: float = None,
    session_id: str = None,
    trace_id: str = None,
    turn_id: int = None,
    agent_id: str = None,
    parent_agent_id: str = None,
    customer_org_id: str = None,
    agent_version: str = None,
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,
    env: str = None,
    event_properties: dict = None,
    groups: dict = None,
) -> str                                         # Returns span_id

ai.track_span(
    user_id: str,
    span_name: str,                              # e.g., "vector_search", "rerank"
    trace_id: str,
    latency_ms: float,
    input_state: dict = None,                    # Arbitrary JSON, respects content_mode
    output_state: dict = None,                   # Arbitrary JSON, respects content_mode
    parent_span_id: str = None,                  # span_id from another track_span()
    is_error: bool = False,
    error_message: str = None,
    session_id: str = None,
    turn_id: int = None,
    agent_id: str = None,
    parent_agent_id: str = None,
    customer_org_id: str = None,
    agent_version: str = None,
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,
    env: str = None,
    event_properties: dict = None,
    groups: dict = None,
) -> str                                         # Returns span_id
```

## Session Management

```python
ai.track_session_end(
    user_id: str,
    session_id: str,
    enrichments: SessionEnrichments = None,      # Optional customer enrichments
    trace_id: str = None,
    turn_id: int = None,
    agent_id: str = None,
    parent_agent_id: str = None,
    customer_org_id: str = None,
    agent_version: str = None,
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,
    env: str = None,
    abandonment_turn: int = None,                # Turn where user abandoned (signals first-response failure when = 1)
    idle_timeout_minutes: int = None,            # Hint to enrichment pipeline for session idle timeout
    event_properties: dict = None,
    groups: dict = None,
)

ai.track_session_enrichment(
    user_id: str,
    session_id: str,
    enrichments: SessionEnrichments,             # Required for customer_enriched mode
    trace_id: str = None,
    turn_id: int = None,
    agent_id: str = None,
    parent_agent_id: str = None,
    customer_org_id: str = None,
    agent_version: str = None,
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,
    env: str = None,
    event_properties: dict = None,
    groups: dict = None,
)
```

## Scoring

```python
ai.score(
    user_id: str,
    name: str,                                    # Score name, e.g., "user-feedback", "accuracy"
    value: float,                                 # Score value (1/0 binary, 0-1 continuous, 1-5 rating)
    target_id: str,                               # The message_id or session_id being scored
    target_type: str = "message",                 # "message" or "session"
    source: str = "user",                         # "user", "ai", "reviewer"
    comment: str = None,                          # Optional text (respects content_mode)
    session_id: str = None,                       # Session context (for linking)
    trace_id: str = None,
    turn_id: int = None,
    agent_id: str = None,
    parent_agent_id: str = None,
    customer_org_id: str = None,
    agent_version: str = None,
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,
    env: str = None,
    event_properties: dict = None,
    groups: dict = None,
)
```

## Bound Agent

```python
ai.agent(
    agent_id: str,
    user_id: str = None,
    parent_agent_id: str = None,
    customer_org_id: str = None,
    agent_version: str = None,                    # e.g., "v4.2", "2025-02-11", git SHA
    description: str = None,                     # Human-readable agent purpose
    context: dict = None,                         # Arbitrary key-value pairs stamped on every event (JSON)
    env: str = None,
    session_id: str = None,
    trace_id: str = None,
    groups: dict = None,
) -> BoundAgent                                   # Pre-configured handle

agent.child(
    agent_id: str,
    **overrides,                                  # Override any inherited field (context dicts are merged)
) -> BoundAgent                                   # Inherits env, customer_org_id, description, agent_version, context, session_id, trace_id, groups; sets parent_agent_id

agent.session(
    session_id: str = None,                       # Auto-generated UUID if omitted
    idle_timeout_minutes: int = None,            # Hint to enrichment pipeline for session idle timeout
    user_id: str = None,                         # Override bound user_id for this session
    device_id: str = None,                       # Browser device ID (for Session Replay linking)
    browser_session_id: str = None,              # Browser session ID (for Session Replay linking)
) -> Session                                      # Context manager; auto track_session_end on exit
```

`BoundAgent` exposes all the same `track_*` methods as `AmplitudeAI`, plus `flush()`, `shutdown()`, `child()`, and `session()`. `Session` exposes `track_*` methods plus `new_trace()`, `set_enrichments()`, and `score()`.

## Lifecycle

```python
ai.flush() -> list[Future]                       # Delegates to amplitude.flush()
ai.shutdown()                                    # Clean exit; only closes if we created client
```

## Utilities

```python
ai.status() -> dict
# Returns current configuration and available providers:
#   content_mode, debug, dry_run, redact_pii,
#   providers_available, patched_providers

ai.tenant(
    customer_org_id: str,                        # Maps to customer_org_id on every event
    groups: dict = None,                         # B2B group properties for this tenant
    env: str = None,                             # e.g., "production", "staging"
) -> TenantHandle                                # Factory -- call .agent() to create BoundAgents
```
