​
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.
​
adaline-api-key
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.
adaline-api-key: ak-live-1234567890abcdef
​
adaline-project-id
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.
adaline-project-id: 4a4b33c9-ee04-46cb-bb99-a727b8a786a1
​
adaline-prompt-id
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.
adaline-prompt-id: 723321e3-774c-4f70-8584-1dfc99e07b89

​
Optional Trace Headers

These headers provide additional context for trace-level observability and monitoring.
​
adaline-trace-name
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
adaline-trace-name: user-onboarding-flow
​
adaline-trace-status
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.
adaline-trace-status: success
​
adaline-trace-reference-id
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.
adaline-trace-reference-id: order-12345-checkout
​
adaline-trace-session-id
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.
adaline-trace-session-id: session_abc123def456
​
adaline-trace-attributes
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’.
adaline-trace-attributes: [{"operation": "create", "key": "user_id", "value": "12345"}, {"operation": "delete", "key": "in_progress"}]
​
adaline-trace-tags
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’.
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.
​
adaline-deployment-id
string
Deployment identifier of the deployment in Adaline.Validation: Must be a string if provided.Usage: Optional. Used for correlating spans with specific deployments.
adaline-deployment-id: deploy_v1.2.3_20231201
​
adaline-span-name
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”
adaline-span-name: generate-product-description
​
adaline-span-run-evaluation
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
adaline-span-run-evaluation: true
​
adaline-span-session-id
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.
adaline-span-session-id: span_session_xyz789
​
adaline-span-reference-id
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.
adaline-span-reference-id: step-3-product-generation
​
adaline-span-variables
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 ContentTypeValidation: 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.
adaline-span-variables: {"product_type": {"modality": "text", "value": "electronics"}, "product_img": {"modality": "image", "detail": "auto", "value": {"type": "url", "url": "https://example.com/product.jpg"}}}
​
adaline-span-attributes
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.
adaline-span-attributes: {"model": "gpt-4", "temperature": 0.7, "max_tokens": 1000}
​
adaline-span-tags
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.
adaline-span-tags: ["llm-call", "content-generation", "user-facing"]

​
Header Usage Examples

​
Basic Request

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

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.