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

# Export Data

> Query and export HoneyHive trace data programmatically via the REST API or SDK to build custom reports, dashboards, and downstream analytics pipelines.

Query your trace data programmatically using the HoneyHive SDK. This is useful for building custom analytics, exporting data for fine-tuning, or integrating with external systems.

## Query Parameters

| Parameter     | Type               | Required | Description                                                                                                        |
| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `filters`     | List\[EventFilter] | No       | Filters to apply                                                                                                   |
| `project`     | String             | No       | Project name. Deprecated - the backend infers the project from filters. Still accepted for backwards compatibility |
| `limit`       | Integer            | No       | Max results per page (default: 1000, max: 7500)                                                                    |
| `page`        | Integer            | No       | Page number (default: 1)                                                                                           |
| `date_range`  | Object             | No       | Date range with `$gte` and `$lte` ISO 8601 strings                                                                 |
| `projections` | List\[String]      | No       | Fields to include in the response                                                                                  |

### EventFilter Fields

| Field      | Type     | Description                                                            |
| ---------- | -------- | ---------------------------------------------------------------------- |
| `field`    | String   | Field to filter on (e.g., `event_type`, `session_id`, `metadata.cost`) |
| `value`    | String   | Value to match                                                         |
| `operator` | Operator | One of: `is_`, `is_not`, `contains`, `not_contains`, `greater_than`    |
| `type`     | Type     | Data type: `string`, `number`, `boolean`, `datetime`                   |

## Setup

```python theme={null}
import os
from honeyhive import HoneyHive
from honeyhive.models import EventFilter
from honeyhive.models.generated import Operator, Type

client = HoneyHive(api_key=os.environ["HH_API_KEY"])
```

<Note>
  The response object (`result`) uses attribute access (e.g., `result.total_events`, `result.events`), while individual events are returned as dictionaries (e.g., `event['event_name']`).
</Note>

## Query Model Events

Retrieve all LLM model events from your project:

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="event_type",
            value="model",
            operator=Operator.is_,
            type=Type.string,
        )
    ],
    limit=100,
)

print(f"Total events: {result.total_events}")
for event in result.events:
    print(f"  {event['event_name']}: {event['duration']}ms")
```

## Query Events in a Session

Get all events belonging to a specific trace/session:

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="session_id",
            value="<SESSION_ID>",
            operator=Operator.is_,
            type=Type.string,
        )
    ],
)

for event in result.events:
    print(f"{event['event_type']}: {event['event_name']}")
```

## Query Sessions

Get session-level data (root events only):

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="event_type",
            value="session",
            operator=Operator.is_,
            type=Type.string,
        )
    ],
    limit=50,
)

for session in result.events:
    # Session metadata includes aggregated stats
    print(f"Session: {session['session_id']}")
    print(f"  Events: {session.get('metadata', {}).get('num_events', 0)}")
    print(f"  Cost: ${session.get('metadata', {}).get('cost', 0):.4f}")
```

## Filter by Evaluator Score

Query events that have a specific evaluator score:

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="event_type",
            value="model",
            operator=Operator.is_,
            type=Type.string,
        ),
        EventFilter(
            field="metrics.Context Relevance",
            value="3",
            operator=Operator.greater_than,
            type=Type.number,
        ),
    ],
    limit=100,
)
```

## Filter by User Feedback

Query events with specific user feedback:

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="feedback.rating",
            value="5",
            operator=Operator.is_,
            type=Type.number,
        ),
    ],
    limit=100,
)
```

## Filter by Metadata

Query events by custom metadata fields:

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="metadata.environment",
            value="production",
            operator=Operator.is_,
            type=Type.string,
        ),
    ],
    limit=100,
)
```

## Filter by Date Range

Query events within a specific time period:

```python theme={null}
result = client.events.get_events(
    filters=[
        EventFilter(
            field="event_type",
            value="model",
            operator=Operator.is_,
            type=Type.string,
        ),
    ],
    date_range={
        "$gte": "2024-01-01T00:00:00.000Z",
        "$lte": "2024-01-31T23:59:59.999Z",
    },
    limit=1000,
)
```

## Available Filter Operators

| Operator     | Python                  | Description        |
| ------------ | ----------------------- | ------------------ |
| Equals       | `Operator.is_`          | Exact match        |
| Not equals   | `Operator.is_not`       | Exclude matches    |
| Contains     | `Operator.contains`     | Substring match    |
| Not contains | `Operator.not_contains` | Exclude substring  |
| Greater than | `Operator.greater_than` | Numeric comparison |

## Common Filterable Fields

| Field                    | Description                            |
| ------------------------ | -------------------------------------- |
| `event_type`             | `session`, `model`, `tool`, or `chain` |
| `event_name`             | Name of the event/span                 |
| `session_id`             | Session/trace ID                       |
| `metrics.<name>`         | Evaluator scores                       |
| `feedback.<name>`        | User feedback values                   |
| `metadata.<name>`        | Custom metadata                        |
| `user_properties.<name>` | User properties                        |

<Note>
  Session events include aggregated metadata like `num_events`, `cost`, `total_tokens`. See [Session Aggregations](/v2/tracing/aggregation-logic) for details.
</Note>

## Export Timeouts and Retries

Export operations (`export()`, `export_async()`, `get_by_session_id()`) use a default read timeout of **300 seconds** to handle large result sets. You can override this with the `HH_EXPORT_TIMEOUT_SECONDS` environment variable:

```bash theme={null}
export HH_EXPORT_TIMEOUT_SECONDS=600  # 10 minutes
```

```python theme={null}
import os
from honeyhive import HoneyHive
os.environ["HH_EXPORT_TIMEOUT_SECONDS"] = "600"

# Must be set before creating the client
client = HoneyHive(api_key=os.environ["HH_API_KEY"])
```

<Note>
  The environment variable must be set **before** the `HoneyHive` client is instantiated. The timeout value must be a positive number (in seconds). If an invalid value is provided, the SDK falls back to the default of 300 seconds.
</Note>

The `export_async()` method automatically retries on transient HTTP errors (502, 503, 504), matching the behavior of `export()`.