Types

Every type exported by the Recount Python SDK, from RecountOptions to table, chart and LLM span data.

The SDK is typed with TypedDicts. Most span option dicts (input, output, metadata, etc.) are plain dicts validated at runtime rather than imported types - pass the fields documented on each span-type page directly. The types below are the ones actually exported from the recount package; import them with:

from recount import (
    RecountOptions,
    TraceOptions,
    RetentionPeriod,
    IngestResult,
    SpanType,
    SpanOptions,
    MessageSpanLevel,
    SpanAlert,
    SpanAlertCheck,
    SpanAlertLevel,
    SpanAlertOptions,
    TableData,
    ChartData,
    ChartSeries,
    ChartType,
    JsonObject,
    Metadata,
    SpanGroup,
    Trace,
    TableBuilder,
    ChartBuilder,
    RecountError,
    REDACTED,
)

Core

`RecountOptions`

class RecountOptions(TypedDict, total=False):
    apiKey: str
    apiUrl: str
    environment: str
    debug: bool

`TraceOptions`

class TraceOptions(TypedDict, total=False):
    environment: str
    metadata: Metadata
    retentionPeriod: RetentionPeriod

`RetentionPeriod`

RetentionPeriod = Literal["1d", "7d", "30d", "90d", "1y"]

`IngestResult`

class IngestResult(TypedDict):
    traceId: str

Spans

`SpanType`

SpanType = Literal[
    "message", "json", "table", "http", "chart", "llm", "image", "db", "group"
]

`SpanOptions`

Broad options dict accepted by add_span. Not every field applies to every span type - see each span-type page for which fields it uses.

class SpanOptions(TypedDict, total=False):
    description: str
    input: Any
    output: Any
    alerts: List["SpanAlert"]
    durationMs: int
    redact: List[str]
    redactParams: List[Any]
    public: bool
    text: str
    level: MessageSpanLevel
    metadata: Any

`MessageSpanLevel`

MessageSpanLevel = Literal["info", "warn", "error"]

Alerts

`SpanAlertLevel`

SpanAlertLevel = Literal["warn", "error"]

`SpanAlertOptions`

Options passed to recount.add_alert() / g.alert(). See Alerts.

class SpanAlertOptions(TypedDict, total=False):
    checks: List[SpanAlertCheck]

`SpanAlert`

The shape stored on a span after add_alert() attaches to it - not something you construct directly.

class SpanAlert(TypedDict, total=False):
    label: str
    level: SpanAlertLevel
    checks: List[SpanAlertCheck]

`SpanAlertCheck`

class SpanAlertCheck(TypedDict, total=False):
    target: str
    value: float

Tables

`TableData`

A single table definition. Pass directly as span input or output.

class TableData(TypedDict, total=False):
    title: str
    columns: List[TableColumn]
    rows: List[List[Any]]              # required when `sections` is not provided
    rowHighlights: List[Optional[TableHighlight]]
    cellHighlights: List[List[Optional[TableHighlight]]]
    summary: List[TableSummaryStat]
    sections: List[TableSection]       # mutually exclusive with `rows`

TableColumn, TableHighlight, TableSummaryStat, and TableSection describe the shape of TableData's fields, but aren't exported for import - build tables with the recount.table() builder rather than constructing TableData by hand.

TableHighlight = Literal["danger", "warn", "success", "info", "muted"]

# TableColumn is either a plain string label, or a dict for spans/highlights:
TableColumn = Union[str, Dict[str, Any]]  # {"label": str, "span"?: int, "highlight"?: TableHighlight}

class TableSummaryStat(TypedDict, total=False):
    text: str
    highlight: TableHighlight

class TableSection(TypedDict, total=False):
    title: str
    rows: List[List[Any]]
    rowHighlights: List[Optional[TableHighlight]]
    cellHighlights: List[List[Optional[TableHighlight]]]
    summary: List[TableSummaryStat]

`TableBuilder`

Returned by recount.table(). See that page for the full method chain.

Charts

`ChartData`

A single chart definition. Pass directly as span input or output.

class ChartData(TypedDict, total=False):
    title: str
    type: ChartType
    labels: List[str]
    series: List[ChartSeries]
    referenceLines: List[ChartReferenceLine]

`ChartType`

ChartType = Literal["line", "bar", "pie", "scatter"]

`ChartSeries`

class ChartSeries(TypedDict, total=False):
    name: str
    data: List[float]

`ChartReferenceLine`

Describes an entry in ChartData["referenceLines"]; not separately exported.

class ChartReferenceLine(TypedDict, total=False):
    value: float
    label: str

`ChartBuilder`

Returned by recount.chart(). See that page for the full method chain.

Database

Database spans don't have a dedicated exported options type - pass a plain dict with metadata, input, output, and optionally redactParams, as shown on the Database spans page. DbSpanMetadata's shape:

class DbSpanMetadata(TypedDict, total=False):
    collection: str
    table: str
    queryType: Literal["sql", "nosql"]

Groups

`SpanGroup`

The g object passed to an add_group builder. See Groups for its span(), add_message(), and alert() methods.

Group options aren't a separately exported type - pass a plain dict with description, limit, sample, and/or sampleThreshold, as shown on the Groups page.

Utilities

`JsonObject`

JsonObject = Union[Dict[str, Any], List[Any]]

`Metadata`

Metadata = Dict[str, Union[str, int, float, bool, None]]

`Trace`

The object returned internally by start_trace while a trace is active. You won't normally construct or hold a reference to this directly - use the module-level recount.add_span / recount.add_group / etc. functions instead, which operate on whichever trace is active in the current async context.

Errors

`RecountError`

Raised internally by the Recount client on a non-OK ingest response. The module-level functions (start_trace, add_span, etc.) swallow ingest errors silently, so you will only encounter this if using the Recount class directly.

class RecountError(Exception):
    status: int

On this page