Forwarding Connectors

Overview

The Confident AI SDK exposes every Forwarding Connector method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Forwarding Connectors

Lists the forwarding connectors in your Confident AI project one page at a time, newest first. Each connector is returned as a summary; retrieve one by id for its headers, environments and delivery history.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.forwarding_connectors.list(page=1, page_size=25)

For async mode, call a_list and await it as shown below:

result = await client.forwarding_connectors.a_list(...)

Parameters

Parameter	Type	Description
`page`	`Optional[int]`	The page to return. Defaults to 1.
`page_size`	`Optional[int]`	The number of results per page, at most 100. Defaults to 25.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.forwardingConnectors.list(
  { page: 1, pageSize: 25 },
);

Parameters

Parameter	Type	Description
`page`	`number`	The page to return. Defaults to 1.
`pageSize`	`number`	The number of results per page, at most 100. Defaults to 25.

Returns

This method returns an object of type ForwardingConnectorList.

Create Forwarding Connector

Creates a forwarding connector in your Confident AI project and returns its id. Confident AI then forwards traces from the environments you selected to your OTLP/HTTP collector, sending the headers you supplied with every batch. Header values are stored write-only: they are masked on every read, so keep your own copy.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.forwarding_connectors.create(
    name="Acme OTLP collector",
    endpoint="https://otlp.acme-observability.com/v1/traces",
    headers=[{"key": "Authorization", "value": "Bearer sk-live-a1b2c3"}],
    environments=["production"],
    enabled=True,
)

For async mode, call a_create and await it as shown below:

result = await client.forwarding_connectors.a_create(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the connector, shown on the Confident AI platform and in forwarding failure messages.
`endpoint`	`str`	Required. The HTTPS URL of the OTLP/HTTP collector that receives the forwarded traces. It must resolve to a public address; private and loopback addresses are rejected.
`headers`	`Optional[List[ForwardingConnectorHeaderConfig]]`	The complete set of HTTP headers to send with every forwarded batch, alongside the `Content-Type: application/x-protobuf` header Confident AI sets. Omit this field to leave the stored headers untouched. When you do send it, the list replaces all stored headers, so resend every header you want to keep — including the ones whose values you read back masked, which are kept as stored. See ForwardingConnectorHeaderConfig.
`environments`	`Optional[List[Environment]]`	The environments whose traces this connector forwards. An empty list forwards traces from every environment. Omit this field to leave the stored environments unchanged. See Environment.
`enabled`	`Optional[bool]`	Whether the connector forwards traces. Defaults to true on create; omit it on an update to leave it unchanged.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.forwardingConnectors.create(
  "Acme OTLP collector",
  "https://otlp.acme-observability.com/v1/traces",
  {
    headers: [{ key: "Authorization", value: "Bearer sk-live-a1b2c3" }],
    environments: ["production"],
    enabled: true
  },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the connector, shown on the Confident AI platform and in forwarding failure messages.
`endpoint`	`string`	Required. The HTTPS URL of the OTLP/HTTP collector that receives the forwarded traces. It must resolve to a public address; private and loopback addresses are rejected.
`headers`	`ForwardingConnectorHeaderConfig[]`	The complete set of HTTP headers to send with every forwarded batch, alongside the `Content-Type: application/x-protobuf` header Confident AI sets. Omit this field to leave the stored headers untouched. When you do send it, the list replaces all stored headers, so resend every header you want to keep — including the ones whose values you read back masked, which are kept as stored. See ForwardingConnectorHeaderConfig.
`environments`	`Environment[]`	The environments whose traces this connector forwards. An empty list forwards traces from every environment. Omit this field to leave the stored environments unchanged. See Environment.
`enabled`	`boolean`	Whether the connector forwards traces. Defaults to true on create; omit it on an update to leave it unchanged.

Returns

This method returns an object of type ForwardingConnectorRef.

Get Forwarding Connector

Retrieves a forwarding connector by id, with its headers, the environments it forwards, and how its deliveries have gone. Header values come back masked, never in plaintext.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.forwarding_connectors.get(
    forwarding_connector_id="<FORWARDING-CONNECTOR-ID>",
)

For async mode, call a_get and await it as shown below:

result = await client.forwarding_connectors.a_get(...)

Parameters

Parameter	Type	Description
`forwarding_connector_id`	`str`	Required. The id of the forwarding connector.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.forwardingConnectors.get(
  "<FORWARDING-CONNECTOR-ID>",
);

Parameters

Parameter	Type	Description
`forwardingConnectorId`	`string`	Required. The id of the forwarding connector.

Returns

This method returns an object of type ForwardingConnector.

Update Forwarding Connector

Updates a forwarding connector and returns it. Every field you omit is left as stored.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.forwarding_connectors.update(
    forwarding_connector_id="<FORWARDING-CONNECTOR-ID>",
    name="Acme OTLP collector",
    endpoint="https://otlp.acme-observability.com/v1/traces",
    headers=[{"key": "Authorization", "value": "Bearer sk-live-a1b2c3"}],
    environments=["production"],
    enabled=True,
)

For async mode, call a_update and await it as shown below:

result = await client.forwarding_connectors.a_update(...)

Parameters

Parameter	Type	Description
`forwarding_connector_id`	`str`	Required. The id of the forwarding connector.
`name`	`Optional[str]`	The name of the connector.
`endpoint`	`Optional[str]`	The HTTPS URL of the OTLP/HTTP collector that receives the forwarded traces. It must resolve to a public address; private and loopback addresses are rejected.
`headers`	`Optional[List[ForwardingConnectorHeaderConfig]]`	The complete set of HTTP headers to send with every forwarded batch, alongside the `Content-Type: application/x-protobuf` header Confident AI sets. Omit this field to leave the stored headers untouched. When you do send it, the list replaces all stored headers, so resend every header you want to keep — including the ones whose values you read back masked, which are kept as stored. See ForwardingConnectorHeaderConfig.
`environments`	`Optional[List[Environment]]`	The environments whose traces this connector forwards. An empty list forwards traces from every environment. Omit this field to leave the stored environments unchanged. See Environment.
`enabled`	`Optional[bool]`	Whether the connector forwards traces. Defaults to true on create; omit it on an update to leave it unchanged.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.forwardingConnectors.update(
  "<FORWARDING-CONNECTOR-ID>",
  {
    name: "Acme OTLP collector",
    endpoint: "https://otlp.acme-observability.com/v1/traces",
    headers: [{ key: "Authorization", value: "Bearer sk-live-a1b2c3" }],
    environments: ["production"],
    enabled: true
  },
);

Parameters

Parameter	Type	Description
`forwardingConnectorId`	`string`	Required. The id of the forwarding connector.
`name`	`string`	The name of the connector.
`endpoint`	`string`	The HTTPS URL of the OTLP/HTTP collector that receives the forwarded traces. It must resolve to a public address; private and loopback addresses are rejected.
`headers`	`ForwardingConnectorHeaderConfig[]`	The complete set of HTTP headers to send with every forwarded batch, alongside the `Content-Type: application/x-protobuf` header Confident AI sets. Omit this field to leave the stored headers untouched. When you do send it, the list replaces all stored headers, so resend every header you want to keep — including the ones whose values you read back masked, which are kept as stored. See ForwardingConnectorHeaderConfig.
`environments`	`Environment[]`	The environments whose traces this connector forwards. An empty list forwards traces from every environment. Omit this field to leave the stored environments unchanged. See Environment.
`enabled`	`boolean`	Whether the connector forwards traces. Defaults to true on create; omit it on an update to leave it unchanged.

Returns

This method returns an object of type ForwardingConnector.

Delete Forwarding Connector

Permanently deletes a forwarding connector and the credentials stored in its headers. Traces already forwarded are unaffected.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.forwarding_connectors.delete(
    forwarding_connector_id="<FORWARDING-CONNECTOR-ID>",
)

For async mode, call a_delete and await it as shown below:

result = await client.forwarding_connectors.a_delete(...)

Parameters

Parameter	Type	Description
`forwarding_connector_id`	`str`	Required. The id of the forwarding connector.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.forwardingConnectors.delete(
  "<FORWARDING-CONNECTOR-ID>",
);

Parameters

Parameter	Type	Description
`forwardingConnectorId`	`string`	Required. The id of the forwarding connector.

Returns

This method returns an object of type ForwardingConnectorRef.

Types

Environment

This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform.

class Environment(Enum):
    PRODUCTION = "production"
    DEVELOPMENT = "development"
    STAGING = "staging"
    TESTING = "testing"

enum Environment {
  PRODUCTION = "production",
  DEVELOPMENT = "development",
  STAGING = "staging",
  TESTING = "testing",
}

PRODUCTION · DEVELOPMENT · STAGING · TESTING

ForwardingConnector

A destination Confident AI forwards your traces to over OTLP/HTTP, with its delivery history. Header values are always masked.

class ForwardingConnector:
    id: str
    name: str
    endpoint: str
    headers: List[ForwardingConnectorHeader]
    environments: List[Environment]
    enabled: bool
    last_forwarded_at: Optional[str] = Field(alias="lastForwardedAt")
    last_error: Optional[str] = Field(alias="lastError")
    success_count: int = Field(alias="successCount")
    failure_count: int = Field(alias="failureCount")
    created_at: str = Field(alias="createdAt")
    updated_at: str = Field(alias="updatedAt")

idstrRequired

The id of the connector, generated by Confident AI.

Example: "<FORWARDING-CONNECTOR-ID>"

namestrRequired

The name of the connector.

Example: "Acme OTLP collector"

endpointstrRequired

The OTLP/HTTP collector the connector forwards traces to.

Example: "https://otlp.acme-observability.com/v1/traces"

headersList[ForwardingConnectorHeader]Required

The HTTP headers sent with every forwarded batch, with every value masked. To change one, resend the whole list with the new value in place and the other values left masked; to leave them all alone, omit headers from the update entirely.

See ForwardingConnectorHeader.

Example: [{"key":"Authorization","value":"***************a1b2c3"}]

environmentsList[Environment]Required

The environments whose traces this connector forwards. An empty list forwards traces from every environment.

See Environment.

Example: ["production"]

enabledboolRequired

Whether the connector is currently forwarding traces.

Example: true

last_forwarded_atOptional[str]Required

When this connector last delivered a batch, or null when it never has.

Example: "2025-01-15T10:30:00+00:00"

last_errorOptional[str]Required

The error from the most recent failed delivery, or null when the last delivery succeeded.

success_countintRequired

How many batches this connector has delivered successfully.

Example: 1284

failure_countintRequired

How many batches this connector has failed to deliver.

Example: 3

created_atstrRequired

When the connector was created.

Example: "2025-01-01T09:00:00+00:00"

updated_atstrRequired

When the connector was last changed.

Example: "2025-01-15T10:29:00+00:00"

interface ForwardingConnector {
  id: string;
  name: string;
  endpoint: string;
  headers: ForwardingConnectorHeader[];
  environments: Environment[];
  enabled: boolean;
  lastForwardedAt: string | null;
  lastError: string | null;
  successCount: number;
  failureCount: number;
  createdAt: string;
  updatedAt: string;
}

idstringRequired

The id of the connector, generated by Confident AI.

Example: "<FORWARDING-CONNECTOR-ID>"

namestringRequired

The name of the connector.

Example: "Acme OTLP collector"

endpointstringRequired

The OTLP/HTTP collector the connector forwards traces to.

Example: "https://otlp.acme-observability.com/v1/traces"

headersForwardingConnectorHeader[]Required

See ForwardingConnectorHeader.

Example: [{"key":"Authorization","value":"***************a1b2c3"}]

environmentsEnvironment[]Required

The environments whose traces this connector forwards. An empty list forwards traces from every environment.

See Environment.

Example: ["production"]

enabledbooleanRequired

Whether the connector is currently forwarding traces.

Example: true

lastForwardedAtstring | nullRequired

When this connector last delivered a batch, or null when it never has.

Example: "2025-01-15T10:30:00+00:00"

lastErrorstring | nullRequired

The error from the most recent failed delivery, or null when the last delivery succeeded.

successCountnumberRequired

How many batches this connector has delivered successfully.

Example: 1284

failureCountnumberRequired

How many batches this connector has failed to deliver.

Example: 3

createdAtstringRequired

When the connector was created.

Example: "2025-01-01T09:00:00+00:00"

updatedAtstringRequired

When the connector was last changed.

Example: "2025-01-15T10:29:00+00:00"

ForwardingConnectorHeader

An HTTP header sent with every forwarded batch. The header name comes back in the clear, but the value is always masked, because a header is where a bearer token or API key lives.

class ForwardingConnectorHeader:
    key: str
    value: str

keystrRequired

The name of the HTTP header, returned exactly as stored.

Example: "Authorization"

valuestrRequired

The masked value of the header: fifteen asterisks followed by the last six characters of the stored value. The stored value itself is never returned. Send this masked value back on an update to keep the header unchanged.

Example: "***************a1b2c3"

interface ForwardingConnectorHeader {
  key: string;
  value: string;
}

keystringRequired

The name of the HTTP header, returned exactly as stored.

Example: "Authorization"

valuestringRequired

Example: "***************a1b2c3"

ForwardingConnectorHeaderConfig

An HTTP header to send with every forwarded batch. Header values are treated as credentials, so they are never readable once stored.

class ForwardingConnectorHeaderConfig:
    key: str
    value: str

keystrRequired

The name of the HTTP header to send.

Example: "Authorization"

valuestrRequired

The value of the header. Send a plaintext value to set or replace it, or send back the masked value you read to keep the stored one. A masked value that matches no stored header of the same name is dropped, because the original cannot be recovered from a mask.

Example: "Bearer sk-live-a1b2c3"

interface ForwardingConnectorHeaderConfig {
  key: string;
  value: string;
}

keystringRequired

The name of the HTTP header to send.

Example: "Authorization"

valuestringRequired

Example: "Bearer sk-live-a1b2c3"

ForwardingConnectorList

One page of forwarding connectors, with the total across all pages.

class ForwardingConnectorList:
    forwarding_connectors: List[ForwardingConnectorSummary] = Field(alias="forwardingConnectors")
    total_forwarding_connectors: int = Field(alias="totalForwardingConnectors")
    page: int
    page_size: int = Field(alias="pageSize")

forwarding_connectorsList[ForwardingConnectorSummary]Required

The forwarding connectors for the current page, newest first.

See ForwardingConnectorSummary.

total_forwarding_connectorsintRequired

The total number of forwarding connectors in this project.

Example: 2

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of forwarding connectors per page.

Example: 25

interface ForwardingConnectorList {
  forwardingConnectors: ForwardingConnectorSummary[];
  totalForwardingConnectors: number;
  page: number;
  pageSize: number;
}

forwardingConnectorsForwardingConnectorSummary[]Required

The forwarding connectors for the current page, newest first.

See ForwardingConnectorSummary.

totalForwardingConnectorsnumberRequired

The total number of forwarding connectors in this project.

Example: 2

pagenumberRequired

The page this response covers.

Example: 1

pageSizenumberRequired

The number of forwarding connectors per page.

Example: 25

ForwardingConnectorRef

A reference to a forwarding connector by its id.

class ForwardingConnectorRef:
    id: str

idstrRequired

The id of the connector, generated by Confident AI.

Example: "<FORWARDING-CONNECTOR-ID>"

interface ForwardingConnectorRef {
  id: string;
}

idstringRequired

The id of the connector, generated by Confident AI.

Example: "<FORWARDING-CONNECTOR-ID>"

ForwardingConnectorSummary

A forwarding connector as it appears in a list: enough to pick one out, without its headers, environments or delivery history. Retrieve it by id for those.

class ForwardingConnectorSummary:
    id: str
    name: str
    endpoint: str
    enabled: bool

idstrRequired

The id of the connector, generated by Confident AI.

Example: "<FORWARDING-CONNECTOR-ID>"

namestrRequired

The name of the connector.

Example: "Acme OTLP collector"

endpointstrRequired

The OTLP/HTTP collector the connector forwards traces to.

Example: "https://otlp.acme-observability.com/v1/traces"

enabledboolRequired

Whether the connector is currently forwarding traces.

Example: true

interface ForwardingConnectorSummary {
  id: string;
  name: string;
  endpoint: string;
  enabled: boolean;
}

idstringRequired

The id of the connector, generated by Confident AI.

Example: "<FORWARDING-CONNECTOR-ID>"

namestringRequired

The name of the connector.

Example: "Acme OTLP collector"

endpointstringRequired

The OTLP/HTTP collector the connector forwards traces to.

Example: "https://otlp.acme-observability.com/v1/traces"

enabledbooleanRequired

Whether the connector is currently forwarding traces.

Example: true

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI