Client API Reference¶

The main entry point for interacting with the Honeycomb API.

HoneycombClient¶

HoneycombClient ¶

Async-first client for the Honeycomb API.

Supports both async and sync usage patterns.

Example (async - recommended): >>> async with HoneycombClient(api_key="your-key") as client: ... datasets = await client.datasets.list() ... triggers = await client.triggers.list(dataset="my-dataset")

Example (sync): >>> with HoneycombClient(api_key="your-key", sync=True) as client: ... datasets = client.datasets.list()

Parameters:

Name	Type	Description	Default
`api_key`	`str \| None`	Honeycomb API key for single-environment access.	`None`
`management_key`	`str \| None`	Management API key ID for multi-environment access.	`None`
`management_secret`	`str \| None`	Management API key secret.	`None`
`base_url`	`str`	API base URL (default: https://api.honeycomb.io).	`DEFAULT_BASE_URL`
`timeout`	`float`	Request timeout in seconds (default: 30).	`DEFAULT_TIMEOUT`
`max_retries`	`int`	Maximum retry attempts for failed requests (default: 3).	`DEFAULT_MAX_RETRIES`
`retry_config`	`RetryConfig \| None`	Custom retry configuration (optional, overrides max_retries).	`None`
`sync`	`bool`	If True, use synchronous HTTP client (default: False).	`False`

triggers `property` ¶

triggers: TriggersResource

Access the Triggers API.

slos `property` ¶

slos: SLOsResource

Access the SLOs API.

datasets `property` ¶

datasets: DatasetsResource

Access the Datasets API.

boards `property` ¶

boards: BoardsResource

Access the Boards API.

queries `property` ¶

queries: QueriesResource

Access the Queries API.

query_annotations `property` ¶

query_annotations: QueryAnnotationsResource

Access the Query Annotations API.

query_results `property` ¶

query_results: QueryResultsResource

Access the Query Results API.

columns `property` ¶

columns: ColumnsResource

Access the Columns API.

derived_columns `property` ¶

derived_columns: DerivedColumnsResource

Access the Derived Columns (Calculated Fields) API.

markers `property` ¶

markers: MarkersResource

Access the Markers API.

recipients `property` ¶

recipients: RecipientsResource

Access the Recipients API.

burn_alerts `property` ¶

burn_alerts: BurnAlertsResource

Access the Burn Alerts API.

events `property` ¶

events: EventsResource

Access the Events API (data ingestion).

api_keys `property` ¶

api_keys: ApiKeysResource

Access the API Keys API (v2 team-scoped).

auth `property` ¶

auth: AuthResource

Access the Auth API.

environments `property` ¶

environments: EnvironmentsResource

Access the Environments API (v2 team-scoped).

service_map_dependencies `property` ¶

service_map_dependencies: ServiceMapDependenciesResource

Access the Service Map Dependencies API.

is_sync `property` ¶

is_sync: bool

Return True if client is in sync mode.

base_url `property` ¶

base_url: str

Return the API base URL.

aclose `async` ¶

aclose() -> None

Close async HTTP client.

close ¶

close() -> None

Close sync HTTP client.

get_async `async` ¶

get_async(
    path: str, *, params: dict | None = None
) -> httpx.Response

Make an async GET request.

post_async `async` ¶

post_async(
    path: str,
    *,
    json: dict | None = None,
    params: dict | None = None,
    headers: dict[str, str] | None = None
) -> httpx.Response

Make an async POST request.

put_async `async` ¶

put_async(
    path: str,
    *,
    json: dict | None = None,
    params: dict | None = None,
    headers: dict[str, str] | None = None
) -> httpx.Response

Make an async PUT request.

patch_async `async` ¶

patch_async(
    path: str,
    *,
    json: dict | None = None,
    params: dict | None = None,
    headers: dict[str, str] | None = None
) -> httpx.Response

Make an async PATCH request.

delete_async `async` ¶

delete_async(
    path: str, *, params: dict | None = None
) -> httpx.Response

Make an async DELETE request.

get_sync ¶

get_sync(
    path: str, *, params: dict | None = None
) -> httpx.Response

Make a sync GET request.

post_sync ¶

post_sync(
    path: str,
    *,
    json: dict | None = None,
    params: dict | None = None,
    headers: dict[str, str] | None = None
) -> httpx.Response

Make a sync POST request.

put_sync ¶

put_sync(
    path: str,
    *,
    json: dict | None = None,
    params: dict | None = None,
    headers: dict[str, str] | None = None
) -> httpx.Response

Make a sync PUT request.

patch_sync ¶

patch_sync(
    path: str,
    *,
    json: dict | None = None,
    params: dict | None = None,
    headers: dict[str, str] | None = None
) -> httpx.Response

Make a sync PATCH request.

delete_sync ¶

delete_sync(
    path: str, *, params: dict | None = None
) -> httpx.Response

Make a sync DELETE request.

Configuration Classes¶

RetryConfig¶

RetryConfig `dataclass` ¶

Configuration for retry behavior.

Attributes:

Name	Type	Description
`max_retries`	`int`	Maximum number of retry attempts.
`base_delay`	`float`	Base delay in seconds for exponential backoff.
`max_delay`	`float`	Maximum delay in seconds between retries.
`exponential_base`	`float`	Base for exponential backoff calculation.
`retry_statuses`	`set[int]`	HTTP status codes that should trigger a retry.

RateLimitInfo¶

RateLimitInfo `dataclass` ¶

Rate limit information from response headers.

Attributes:

Name	Type	Description
`limit`	`int \| None`	Total requests allowed in the time window.
`remaining`	`int \| None`	Remaining requests in the current time window.
`reset`	`int \| None`	Seconds until the rate limit resets.

Usage Examples¶

Basic Async Client¶

import asyncio
from honeycomb import HoneycombClient

async def main():
    async with HoneycombClient(api_key="your-key") as client:
        datasets = await client.datasets.list_async()
        print(f"Found {len(datasets)} datasets")

asyncio.run(main())

Sync Client¶

from honeycomb import HoneycombClient

with HoneycombClient(api_key="your-key", sync=True) as client:
    datasets = client.datasets.list()

Custom Configuration¶

from honeycomb import HoneycombClient, RetryConfig

retry_config = RetryConfig(
    max_retries=5,
    base_delay=2.0,
    max_delay=60.0,
    retry_statuses={429, 503},
)

async with HoneycombClient(
    api_key="your-key",
    base_url="https://api.honeycomb.io",
    timeout=30.0,
    retry_config=retry_config,
) as client:
    # Your code here
    pass

Management Key Authentication¶

from honeycomb import HoneycombClient

async with HoneycombClient(
    management_key="your-key-id",
    management_secret="your-secret"
) as client:
    # Management operations
    pass

Client API Reference¶

HoneycombClient¶

HoneycombClient ¶

triggers property ¶

slos property ¶

datasets property ¶

boards property ¶

queries property ¶

query_annotations property ¶

query_results property ¶

columns property ¶

derived_columns property ¶

markers property ¶

recipients property ¶

burn_alerts property ¶

events property ¶

api_keys property ¶

auth property ¶

environments property ¶

service_map_dependencies property ¶

is_sync property ¶

base_url property ¶

aclose async ¶