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

# Headers

> Complete reference for all Proxy headers

# Headers

Complete reference for all headers supported by Proxy, including required headers, optional trace headers, and optional span headers.

## Required Headers

These headers must be included with every request to Proxy.

<ParamField body="adaline-api-key" type="string" required>
  Your Adaline workspace API key for authentication.

  **Validation:** Must be a non-empty string and a valid Adaline API key.

  **Usage:** Required with every request for authentication.
</ParamField>

```http theme={null}
adaline-api-key: ak-live-1234567890abcdef
```

<ParamField body="adaline-project-id" type="string" required>
  Your Adaline project identifier to associate telemetry data.

  **Validation:** Must be a non-empty string and a valid project ID that your API key has access to.

  **Usage:** Required with every request to identify the project to create the trace.
</ParamField>

```http theme={null}
adaline-project-id: 4a4b33c9-ee04-46cb-bb99-a727b8a786a1
```

<ParamField body="adaline-prompt-id" type="string" required>
  Your Adaline prompt identifier for tracking specific prompts.

  **Validation:** Must be a non-empty string and a valid prompt ID within your project.

  **Usage:** Required with every request to identify the prompt to create the span.
</ParamField>

```http theme={null}
adaline-prompt-id: 723321e3-774c-4f70-8584-1dfc99e07b89

```

## Optional Trace Headers

These headers provide additional context for trace-level observability and monitoring.

<ParamField body="adaline-trace-name" type="string">
  Custom name for the trace to help identify it in the Adaline.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for organizing and filtering traces in the Adaline.

  **Default:** Proxy
</ParamField>

```http theme={null}
adaline-trace-name: user-onboarding-flow
```

<ParamField body="adaline-trace-status" type="string">
  Status of the trace execution.

  **Validation:** Must be one of: "success", "failure", "pending", "unknown".

  **Usage:** Optional. Used for tracking trace completion status.

  **Default:** Adaline will set the status based on the response from the AI provider.
</ParamField>

```http theme={null}
adaline-trace-status: success
```

<ParamField body="adaline-trace-reference-id" type="string">
  External reference ID to correlate with your application's tracking systems and group different spans into a single trace.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for correlating traces with external systems. If not provided, each span will be a separate trace in Adaline.
</ParamField>

```http theme={null}
adaline-trace-reference-id: order-12345-checkout
```

<ParamField body="adaline-trace-session-id" type="string">
  Session identifier to group related traces together.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for filter and grouping traces within a session of your application.
</ParamField>

```http theme={null}
adaline-trace-session-id: session_abc123def456
```

<ParamField body="adaline-trace-attributes" type="string">
  JSON object containing custom attributes for the trace.

  **Validation:** Must be a valid JSON string if provided.

  **Usage:** Optional. Used for adding custom metadata to traces.
  Each attribute operation must specify an operation type: "create" or "delete".
  To modify an existing attribute, use two operations: one to delete the existing attribute and one to create the new one in the same request.
  You can mutate the attributes across multiple requests as long as they have the same 'adaline-trace-reference-id'.
</ParamField>

```http theme={null}
adaline-trace-attributes: [{"operation": "create", "key": "user_id", "value": "12345"}, {"operation": "delete", "key": "in_progress"}]
```

<ParamField body="adaline-trace-tags" type="string">
  JSON array of tags for categorizing and filtering traces.

  **Validation:** Must be a valid JSON array if provided.

  **Usage:** Optional. Used for categorizing traces with searchable tags.
  Each tag operation must specify an operation type: "create" or "delete".
  To modify an existing tag, use two operations: one to delete the existing tag and one to create the new one in the same request.
  You can mutate the tags across multiple requests as long as they have the same 'adaline-trace-reference-id'.
</ParamField>

```http theme={null}
adaline-trace-tags: [{"operation": "create", "tag": "production"}, {"operation": "delete", "tag": "high-priority"}]
```

## Optional Span Headers

These headers provide additional context for span-level observability within traces.

<ParamField body="adaline-deployment-id" type="string">
  Deployment identifier of the deployment in Adaline.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for correlating spans with specific deployments.
</ParamField>

```http theme={null}
adaline-deployment-id: deploy_v1.2.3_20231201
```

<ParamField body="adaline-span-name" type="string">
  Custom name for the span to help identify it within a trace.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for organizing spans within traces.

  **Default:** External name of the type of request aka "Complete Chat" or "Stream Chat" or "Get Embeddings"
</ParamField>

```http theme={null}
adaline-span-name: generate-product-description
```

<ParamField body="adaline-span-run-evaluation" type="string">
  Boolean flag to indicate whether this span 'output' should be evaluated.

  **Validation:** Must be "true" or "false" if provided.

  **Usage:** Optional. Used for enabling/disabling evaluation on specific spans, overriding the continuous evaluation rate set in Adaline.

  **Default:** false
</ParamField>

```http theme={null}
adaline-span-run-evaluation: true
```

<ParamField body="adaline-span-session-id" type="string">
  Session identifier to group related traces together.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for filter and grouping spans within a session of your application.
</ParamField>

```http theme={null}
adaline-span-session-id: span_session_xyz789
```

<ParamField body="adaline-span-reference-id" type="string">
  External reference ID to correlate this span with your application's tracking.

  **Validation:** Must be a string if provided.

  **Usage:** Optional. Used for correlating spans with external systems.
</ParamField>

```http theme={null}
adaline-span-reference-id: step-3-product-generation
```

<ParamField body="adaline-span-variables" type="string">
  JSON object containing variables used in this specific span.
  Variables are dynamic values assigned to placeholders in your prompt, for eg. end user input, fetched context, session chat history, etc.
  `key` is the variable name and `value` is the variable value of type [ContentType](/docs/reference/sdk/v2/typescript/types/MessageContent)

  **Validation:** Must be a valid JSON string if provided.

  **Usage:** Optional. Used for adding variables values to a dataset, playground, etc. in Adaline to iterate and evaluate on your prompt on.
</ParamField>

```http theme={null}
adaline-span-variables: {"product_type": {"modality": "text", "value": "electronics"}, "product_img": {"modality": "image", "detail": "auto", "value": {"type": "url", "url": "https://example.com/product.jpg"}}}
```

<ParamField body="adaline-span-attributes" type="string">
  JSON object containing custom attributes for this span.

  **Validation:** Must be a valid JSON string if provided.

  **Usage:** Optional. Used for adding custom metadata to spans.
</ParamField>

```http theme={null}
adaline-span-attributes: {"model": "gpt-4", "temperature": 0.7, "max_tokens": 1000}
```

<ParamField body="adaline-span-tags" type="string">
  JSON array of tags for categorizing and filtering this span.

  **Validation:** Must be a valid JSON array if provided.

  **Usage:** Optional. Used for categorizing spans with searchable tags.
</ParamField>

```http theme={null}
adaline-span-tags: ["llm-call", "content-generation", "user-facing"]
```

## Header Usage Examples

### Basic Request

```http theme={null}
POST /v1/openai/chat/completions
Content-Type: application/json
adaline-api-key: sk-adaline-1234567890abcdef
adaline-project-id: proj_1234567890abcdef
adaline-prompt-id: prompt_1234567890abcdef

{
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "Hello, world!"}]
}
```

### Request with additional trace and span context

```http theme={null}
POST /v1/openai/chat/completions
Content-Type: application/json
adaline-api-key: ak-live-1234567890abcdef
adaline-project-id: 4a4b33c9-ee04-46cb-bb99-a727b8a786a1
adaline-prompt-id: 723321e3-774c-4f70-8584-1dfc99e07b89
adaline-trace-status: pending
adaline-trace-name: customer-support-chat
adaline-trace-session-id: session_abc123
adaline-trace-reference-id: 2a0024e0-3e0e-45e4-9ee3-6b5c00efe1ea
adaline-trace-attributes: [{"operation": "create", "key": "user_id", "value": "12345"}, {"operation": "create", "key": "department", "value": "support"}, {"operation": "delete", "key": "in_progress"}]
adaline-span-name: generate-chat-response
adaline-span-reference-id: 1b53e2fc-0576-4f76-a6d4-f08e69ae8634
adaline-span-variables: {"order_id": {"modality": "text", "value": "123412"}}

{
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "I need help with my order number 123412"}]
}
```

## Best Practices

### Organization

* Use 'adaline-trace-reference-id' to group related requests (aka spans) into a single trace to get a Gantt chart view in Adaline.
* Group related requests using session IDs to track all traces of a session in Adaline.
* Use trace and span reference IDs to correlate with your existing tracking systems.

### Evaluations

* Use 'adaline-span-run-evaluation' to enable/disable evaluation on specific spans, overriding the continuous evaluation rate set in Adaline.
* Use 'adaline-span-variables' to add variables values to a dataset, playground, etc. in Adaline to iterate and evaluate on your prompt later on.

### Debugging

* Include meaningful trace and span names for easier workflow identification in Adaline.
* Use attributes and tags to capture relevant context for troubleshooting.

### Security

* Never log or expose your `adaline-api-key` in client-side code.
* Store API keys securely using environment variables or secret management systems.