> This page is for version 0.10.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.10: https://docs.nvidia.com/nemo-helix/v0.10/llms.txt
> - 0.9: https://docs.nvidia.com/nemo-helix/v0.9/llms.txt
> - 0.8: https://docs.nvidia.com/nemo-helix/v0.8/llms.txt
> - 0.7: https://docs.nvidia.com/nemo-helix/v0.7/llms.txt
> - 0.6: https://docs.nvidia.com/nemo-helix/v0.6/llms.txt
> - 0.5: https://docs.nvidia.com/nemo-helix/v0.5/llms.txt

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

# Ingest Spans

POST http://localhost:8080/apis/intake/v2/workspaces/{workspace}/ingest/spans
Content-Type: application/json

Reference: https://docs.nvidia.com/nemo-helix/documentation/reference/api-reference/ingest/spans-apis-intake-v-2-workspaces-workspace-ingest-spans-post

## Request

### Path parameters

- `workspace` (string, required)

### Body (application/json)

This endpoint expects a DirectSpansIngestRequest.

- `source` (string, required) — Stable name for the source trace store, such as `langsmith` or `mlflow`.
- `spans` (list of DirectSpanInput, required)

## Response

### 201

Successful Response

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### DirectSpanInput

One provider-neutral span supplied by a historical trace importer.

- `span_id` (string, required)
- `trace_id` (string, required)
- `started_at` (datetime, required)
- `session_id` (string, optional)
- `parent_span_id` (string, optional)
- `name` (string, optional, default: )
- `kind` (enum, optional, default: UNKNOWN)
  - Allowed values: `LLM`, `CHAIN`, `TOOL`, `RETRIEVER`, `EMBEDDING`, `AGENT`, `RERANKER`, `EVALUATOR`, `GUARDRAIL`, `UNKNOWN`
- `status` (enum, optional, default: unknown)
  - Allowed values: `success`, `error`, `cancelled`, `unknown`
- `ended_at` (datetime, optional)
- `input` (any, optional)
- `output` (any, optional)
- `attributes` (map from string to any, optional)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (map from string to any, optional)

### ValidationErrorLocItems

- string
- integer

## Examples

**Request**

```json
{
  "source": "string",
  "spans": [
    {
      "span_id": "string",
      "trace_id": "string",
      "started_at": "2024-01-15T09:30:00Z"
    }
  ]
}
```

**Response**

```json
{}
```

**SDK Code**

```python
import requests

url = "http://localhost:8080/apis/intake/v2/workspaces/default/ingest/spans"
headers = {"Content-Type": "application/json"}
payload = "{\"source\": \"my-agent\", \"spans\": [{\"trace_id\": \"my-trace\", \"span_id\": \"my-span\", \"name\": \"Agent request\", \"started_at\": \"__NHX_CURRENT_TIMESTAMP__\", \"input\": \"Hello!\", \"output\": \"Hello from Helix!\"}]}"
from datetime import datetime, timezone
payload = payload.replace("__NHX_CURRENT_TIMESTAMP__", datetime.now(timezone.utc).isoformat())

response = requests.request("POST", url, headers=headers, data=payload)
response.raise_for_status()
print(response.status_code)  # no response body

```

```javascript
const payload = "{\"source\": \"my-agent\", \"spans\": [{\"trace_id\": \"my-trace\", \"span_id\": \"my-span\", \"name\": \"Agent request\", \"started_at\": \"__NHX_CURRENT_TIMESTAMP__\", \"input\": \"Hello!\", \"output\": \"Hello from Helix!\"}]}".replace("__NHX_CURRENT_TIMESTAMP__", new Date().toISOString());
const response = await fetch("http://localhost:8080/apis/intake/v2/workspaces/default/ingest/spans", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: payload,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(response.status); // no response body

```