> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/v4/sdk-reference/trace-connections/create/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server.

# Create a trace connection

POST https://api.getzep.com/api/v4/trace-connections
Content-Type: application/json

Verify the provider credential before Zep stores it. Example request: `{"name":"Support traces","provider":"braintrust","credential":"secret","requests_per_minute":10}`.

Reference: https://docs-beta.getzep.com/sdk-reference/trace-connections/create

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key  `) — Type "Api-Key" followed by a space and the project API key.

## Request

### Body (application/json)

This endpoint expects a v4.CreateTraceConnectionRequest.

- `api_url` (string, optional) — APIURL is an optional custom provider endpoint.
- `credential` (string, optional) — Credential is the write-only provider credential.
- `name` (string, optional) — Name is the connection name.
- `provider` (string, optional) — Provider is the provider name.
- `requests_per_minute` (integer, optional) — RequestsPerMinute is the provider request rate limit.
- `retention_days` (integer, optional) — RetentionDays is an optional provider retention window.

## Response

### 201

Created

- `created_at` (string, optional) — CreatedAt is the resource creation time.
- `credential_hint` (string, optional) — CredentialHint contains the final four characters of the credential.
- `credential_version` (integer, optional) — CredentialVersion is the current credential version.
- `import_count` (integer, optional) — ImportCount is the number of non-deleted imports that use this connection.
- `last_verified_at` (string, optional) — LastVerifiedAt is the last successful credential verification time.
- `name` (string, optional) — Name is the display name.
- `provider` (string, optional) — Provider is the observability provider.
- `provider_organization_id` (string, optional) — ProviderOrganizationID is the provider organization identifier.
- `provider_organization_name` (string, optional) — ProviderOrganizationName is the provider organization name.
- `settings` (v4.TraceConnectionSettings, optional) — Settings contains provider request and retention settings. Example: \{"requests\_per\_minute":10}.
- `status` (string, optional) — Status is the provider verification status.
- `updated_at` (string, optional) — UpdatedAt is the last resource update time.
- `uuid` (string, optional) — UUID is the trace connection identifier.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (v4.ErrorBody, optional)

### 401 Unauthorized Error

Unauthorized

- `error` (v4.ErrorBody, optional)

### 403 Forbidden Error

Forbidden

- `error` (v4.ErrorBody, optional)

### 422 Unprocessable Entity Error

Unprocessable Entity

- `error` (v4.ErrorBody, optional)

## Types

### v4.TraceConnectionSettings

- `api_url` (string, optional) — APIURL is an optional custom provider endpoint.
- `requests_per_minute` (integer, optional) — RequestsPerMinute is the maximum provider request rate.
- `retention_days` (integer, optional) — RetentionDays is the provider retention window, when known.

### v4.ErrorBody

- `code` (string, optional)
- `details` (map from string to any, optional)
- `message` (string, optional)
- `param` (string, optional)
- `request_id` (string, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "created_at": "2026-01-01T00:00:00Z",
  "credential_hint": "1234",
  "credential_version": 1,
  "import_count": 2,
  "last_verified_at": "2026-01-01T00:00:00Z",
  "name": "Support traces",
  "provider": "braintrust",
  "provider_organization_id": "org_123",
  "provider_organization_name": "Example organization",
  "settings": {
    "api_url": "https://api.braintrust.dev",
    "requests_per_minute": 10,
    "retention_days": 30
  },
  "status": "active",
  "updated_at": "2026-01-01T00:00:00Z",
  "uuid": "8c78a85e-eac2-4f57-b5f5-59a68a1e77a1"
}
```