> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Ingest spans (legacy)

POST https://api.respan.ai/api/v1/traces/ingest
Content-Type: application/json

Accepts spans as a JSON array or an object whose `data` field contains the array. Each span uses the fields in [Create a span](/docs/apis/spans/create-span), plus `trace_unique_id`, `span_unique_id`, and optional `span_parent_id` to build the trace tree. For new integrations, use [Ingest traces (OTLP)](/docs/apis/traces/ingest-traces-otlp).

Reference: https://respan.ai/docs/apis/traces/ingest-spans-legacy

## Authentication

- `Authorization` header (bearer token, required) — Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer \<RESPAN\_API\_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan\_params.credential\_override in the request body, not in this authentication field.

## Request

### Body (application/json)

This endpoint expects a Traces_createTraceLegacy_Request.

- `Traces_createTraceLegacy_Request`

## Response

### 200

Trace spans processed successfully

- `message` (string, required) — Human-readable ingest summary.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (string, required)

### 403 Forbidden Error

The API key is missing, invalid or expired.

- `detail` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (string, optional)

## Types

### TracesCreateTraceLegacyRequest1

Wrapper object accepted by the legacy integration endpoint.

- `data` (list of ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItems, required) — Array of span objects to ingest as traces.

### ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItems

- `trace_unique_id` (string, required) — Trace ID linking all spans.
- `span_unique_id` (string, required) — Unique ID for this span.
- `span_parent_id` (string, optional, nullable) — Parent span ID. `null` for root spans.
- `span_name` (string, optional) — Name of this span.
- `span_workflow_name` (string, optional) — Workflow name.
- `log_type` (enum, optional, default: chat) — Span type.
  - Allowed values: `chat`, `completion`, `response`, `embedding`, `speech`, `transcription`, `workflow`, `agent`, `task`, `tool`, `guardrail`, `reranker`, `other`
- `input` (any, optional) — Input to the model.
- `output` (any, optional) — Output from the model.
- `model` (string, optional) — Model used.
- `usage` (ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsUsage, optional) — Token usage.
- `cost` (double, optional) — Cost in USD.
- `latency` (double, optional) — Latency in seconds.
- `status` (enum, optional)
  - Allowed values: `success`, `error`
- `timestamp` (datetime, optional) — When completed (ISO 8601).
- `start_time` (datetime, optional) — When started (ISO 8601).
- `customer_identifier` (string, optional) — End user identifier.
- `metadata` (ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsMetadata, optional) — Arbitrary key-value pairs.
- `span_path` (string, optional) — Nested path within the workflow.
- `encoding_format` (string, optional) — Embedding encoding format for embedding spans.
- `provider_id` (string, optional) — LLM or service provider ID.
- `prompt_tokens` (integer, optional) — Number of prompt tokens used.
- `completion_tokens` (integer, optional) — Number of completion tokens used.
- `warnings` (string, optional) — Warnings captured during span execution.
- `disable_log` (boolean, optional, default: false) — Set `true` to disable logging for this span.
- `disable_fallback` (boolean, optional, default: false) — Disable fallback behavior for this span.
- `respan_params` (ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsRespanParams, optional) — Additional Respan parameters (e.g. `has_webhook`, `environment`).
- `temperature` (double, optional) — LLM temperature (0-2).
- `presence_penalty` (double, optional) — Presence penalty for LLM requests.
- `frequency_penalty` (double, optional) — Frequency penalty for LLM requests.
- `max_tokens` (integer, optional) — Maximum tokens for completion.
- `stream` (boolean, optional, default: false) — Whether the response was streamed.

### ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsUsage

Token usage.

### ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsMetadata

Arbitrary key-value pairs.

### ApiV1TracesIngestPostRequestBodyContentApplicationJsonSchemaOneOf1DataItemsRespanParams

Additional Respan parameters (e.g. `has_webhook`, `environment`).

## Examples

**Request**

```json
[
  {
    "trace_unique_id": "trace_abc123",
    "span_unique_id": "span_001"
  }
]
```

**Response**

```json
{
  "message": "Processed 2 Vercel spans"
}
```

**SDK Code**

```python Traces_createTraceLegacy_example
import requests

url = "https://api.respan.ai/api/v1/traces/ingest"

payload = [
    {
        "trace_unique_id": "trace_abc123",
        "span_unique_id": "span_001"
    }
]
headers = {
    "Authorization": "Bearer <respanApiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Traces_createTraceLegacy_example
const url = 'https://api.respan.ai/api/v1/traces/ingest';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <respanApiKey>', 'Content-Type': 'application/json'},
  body: '[{"trace_unique_id":"trace_abc123","span_unique_id":"span_001"}]'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Traces_createTraceLegacy_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.respan.ai/api/v1/traces/ingest"

	payload := strings.NewReader("[\n  {\n    \"trace_unique_id\": \"trace_abc123\",\n    \"span_unique_id\": \"span_001\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <respanApiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Traces_createTraceLegacy_example
require 'uri'
require 'net/http'

url = URI("https://api.respan.ai/api/v1/traces/ingest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <respanApiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"trace_unique_id\": \"trace_abc123\",\n    \"span_unique_id\": \"span_001\"\n  }\n]"

response = http.request(request)
puts response.read_body
```

```java Traces_createTraceLegacy_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.respan.ai/api/v1/traces/ingest")
  .header("Authorization", "Bearer <respanApiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"trace_unique_id\": \"trace_abc123\",\n    \"span_unique_id\": \"span_001\"\n  }\n]")
  .asString();
```

```php Traces_createTraceLegacy_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.respan.ai/api/v1/traces/ingest', [
  'body' => '[
  {
    "trace_unique_id": "trace_abc123",
    "span_unique_id": "span_001"
  }
]',
  'headers' => [
    'Authorization' => 'Bearer <respanApiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Traces_createTraceLegacy_example
using RestSharp;

var client = new RestClient("https://api.respan.ai/api/v1/traces/ingest");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <respanApiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"trace_unique_id\": \"trace_abc123\",\n    \"span_unique_id\": \"span_001\"\n  }\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Traces_createTraceLegacy_example
import Foundation

let headers = [
  "Authorization": "Bearer <respanApiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  [
    "trace_unique_id": "trace_abc123",
    "span_unique_id": "span_001"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.respan.ai/api/v1/traces/ingest")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```