Observability | OpenRouter Python SDK | OpenRouter

The Python SDK and docs are currently in beta. Report issues on GitHub.

Overview

Observability endpoints

Available Operations

list - List observability destinations
create - Create an observability destination
delete - Delete an observability destination
get - Get an observability destination
update - Update an observability destination

list

List the observability destinations configured for the authenticated entity’s default workspace. Use the workspace_id query parameter to scope the result to a different workspace. Only destinations with stable release status are surfaced — destinations of other types are excluded. Management key required.

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.observability.list()
12 
13     while res is not None:
14         # Handle items
15 
16         res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`offset`	Optional[int]	➖	Number of records to skip for pagination	0
`limit`	Optional[int]	➖	Maximum number of records to return (max 100)	50
`workspace_id`	Optional[str]	➖	Optional workspace ID to filter by. Defaults to the authenticated entity’s default workspace.	550e8400-e29b-41d4-a716-446655440000
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

operations.ListObservabilityDestinationsResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

create

Create a new observability destination. A maximum of 5 destinations per type is allowed. Defaults to the authenticated entity’s default workspace; use the workspace_id body field to scope to a different workspace. Management key required.

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.observability.create(config={
12         "baseUrl": "https://us.cloud.langfuse.com",
13         "publicKey": "pk-l...EfGh",
14         "secretKey": "sk-l...AbCd",
15     }, name="Production Langfuse", type_="langfuse", enabled=True, privacy_mode=False)
16 
17     # Handle response
18     print(res)

Parameters

Parameter	Type	Required	Description	Example
`config`	Dict[str, Nullable[Any]]	✔️	Provider-specific configuration. The shape depends on `type` and is validated server-side.	`{"baseUrl": "https://us.cloud.langfuse.com","publicKey": "pk-l...EfGh","secretKey": "sk-l...AbCd"}`
`name`	str	✔️	Human-readable name for the destination.	Production Langfuse
`type`	components.CreateObservabilityDestinationRequestType	✔️	The destination type. Only stable destination types are accepted.	langfuse
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`api_key_hashes`	List[str]	➖	Optional allowlist of OpenRouter API key hashes whose traffic is forwarded. `null` or omitted means all keys. Must contain at least one hash if provided.	`<nil>`
`enabled`	Optional[bool]	➖	Whether this destination should be enabled immediately.	true
`filter_rules`	OptionalNullable[components.ObservabilityFilterRulesConfig]	➖	Optional structured filter rules controlling which events are forwarded.	`<nil>`
`privacy_mode`	Optional[bool]	➖	When true, request/response bodies are not forwarded — only metadata.	false
`sampling_rate`	Optional[float]	➖	Sampling rate between 0 and 1 (1 = 100%).	1
`workspace_id`	Optional[str]	➖	Optional workspace ID. Defaults to the authenticated entity’s default workspace.	550e8400-e29b-41d4-a716-446655440000
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.CreateObservabilityDestinationResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.ConflictResponseError	409	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

delete

Delete an existing observability destination. This performs a soft delete. Management key required.

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.observability.delete(id="99999999-aaaa-bbbb-cccc-dddddddddddd")
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✔️	The destination ID (UUID).	99999999-aaaa-bbbb-cccc-dddddddddddd
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.DeleteObservabilityDestinationResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get

Fetch a single observability destination by its UUID. Management key required.

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.observability.get(id="99999999-aaaa-bbbb-cccc-dddddddddddd")
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✔️	The destination ID (UUID).	99999999-aaaa-bbbb-cccc-dddddddddddd
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.GetObservabilityDestinationResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

update

Update an existing observability destination. Only the fields provided in the request body are updated. Management key required.

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.observability.update(id="99999999-aaaa-bbbb-cccc-dddddddddddd", enabled=False, name="Updated Langfuse")
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description	Example
`id`	str	✔️	The destination ID (UUID).	99999999-aaaa-bbbb-cccc-dddddddddddd
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`api_key_hashes`	List[str]	➖	Optional allowlist of OpenRouter API key hashes. `null` clears the filter (all keys). Omitting leaves the current value. Must contain at least one hash if provided.	`<nil>`
`config`	Dict[str, Nullable[Any]]	➖	Provider-specific configuration fields to update. Masked values are ignored; unset fields keep their current value.	`{"baseUrl": "https://us.cloud.langfuse.com","publicKey": "pk-l...EfGh","secretKey": "sk-l...AbCd"}`
`enabled`	Optional[bool]	➖	Whether the destination is enabled.	true
`filter_rules`	OptionalNullable[components.ObservabilityFilterRulesConfig]	➖	N/A	`<nil>`
`name`	Optional[str]	➖	Human-readable name for the destination.	Production Langfuse
`privacy_mode`	Optional[bool]	➖	When true, request/response bodies are not forwarded — only metadata.	false
`sampling_rate`	Optional[float]	➖	Sampling rate between 0 and 1 (1 = 100%).	1
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.UpdateObservabilityDestinationResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.ConflictResponseError	409	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/