---
title: "POST /api/v1/traces"
method: POST
path: "/api/v1/traces"
tags: ["Traces"]
---

# POST /api/v1/traces

`POST /api/v1/traces`

Create traces with feedback

## Request body

- TraceCreateRequest[]
  - `modelId` string, required — Identifier (or alias) for the model that produced the trace.
  - `projectId` string, uuid — Project identifier that groups this trace. Leave empty to keep it unassigned.
  - `input` string, required — Prompt or message provided to the model.
  - `output` string, required — Model response captured for the trace.
  - `score` number, required — Evaluator score used to determine if the trace is positive.
  - `feedback` string, nullable — Optional feedback explaining the score or providing guidance.

## Response `200`

success response

- TraceCreateResponse
  - `results` TraceCreateResult[], required — One entry per trace provided in the request.
    - `traceId` string, uuid, required — Identifier of the newly created trace.
    - `success` boolean, required — Whether the trace was persisted successfully.

## Other responses

- `400` — bad request
- `401` — unauthenticated
- `403` — unauthorized
- `404` — not found
- `409` — conflict
- `500` — internal server error

## Changes

- **2025-11-12** `d71329d1d771` — 4 breaking, 2 info
  - the request property `items/projectId` became not nullable
  - the request property `items/score` became not nullable
  - the request property `items/score` became required
  - the response's body type/format changed from `array`/`` to `object`/`` for status `200`
  - …2 more
- **2025-11-12** `25d63a01824a` — 1 warning, 4 info
  - the `items/feedback` request property's maxLength was set to `2048`
  - added the optional property `items/processingStatus` to the response with the `200` status
  - added the required property `items/addedToDataset` to the response with the `200` status
  - added the required property `items/createdAt` to the response with the `200` status
  - …1 more
- **2025-09-23** `4f595e224e0c` — 1 breaking
  - the `items/score` request property's max was decreased to `1.00`
- **2025-09-09** `25b5483d62a9` — 6 breaking, 11 warning
  - the request's body type/format changed from `object`/`` to `array`/``
  - the response's body type/format changed from `object`/`` to `array`/`` for status `200`
  - removed the required property `id` from the response with the `200` status
  - removed the required property `input` from the response with the `200` status
  - …13 more
- **2025-09-04** `6fce808cc14e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/premai-io/apis/prem-studio-api/changes/api/v1/traces/post.md)

---

[API](https://skmtc.dev/premai-io/apis/prem-studio-api.md) · [All operations](https://skmtc.dev/premai-io/apis/prem-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/premai-io/prem-studio-api/revisions/2cb1f5df1b89/schema)