---
title: "Create project score"
method: POST
path: "/v1/projects/{projectSlug}/scores"
tags: ["Scores"]
---

# Create project score

`POST /v1/projects/{projectSlug}/scores`

Creates a score against a target trace. The trace is resolved by explicit id (`trace.by = "id"`) or by a filter set (`trace.by = "filters"`, exactly one match required). Annotations use the separate `/annotations` endpoint.

## Path parameters

- `projectSlug` string, required — Project slug (human-readable identifier)

## Request body

- union
  - CreateCustomScoreBody
    - `simulationId` string, nullable — Simulation this score is tied to, if any. `null` (default) when not part of a simulation.
    - `value` number, required — Normalized score value in [0, 1]. Higher = better.
    - `passed` boolean, required — Whether the scored output passes the evaluator's bar.
    - `feedback` string, required — Free-text feedback explaining the score.
    - `error` string, nullable — Generation error text, when score generation itself failed. `null` (default) for successful scores.
    - `duration` integer — Score generation duration in nanoseconds. `0` for externally-computed scores.
    - `tokens` integer — LLM tokens consumed generating the score, if any. `0` for externally-computed scores.
    - `cost` integer — Score cost in microcents (100,000,000 per USD). `0` for externally-computed scores.
    - `trace` union, required — Target trace. Either an explicit id or a filter set matching exactly one trace.
      - object
        - `by` 'id', required — Match a single trace by its identifier. Pair with `id`.
        - `id` string, required — 32-character trace identifier.
      - object
        - `by` 'filters', required — Match a single trace by a filter set. Pair with `filters`; exactly one trace must match.
        - `filters` FilterSet, required — Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set.
    - `sourceId` string, required — User-supplied tag identifying the score's origin (e.g. `"prod-pipeline"`, `"qa-script-v2"`).
    - `metadata` object — Arbitrary user-supplied metadata persisted alongside the score.
    - `_evaluation` false — Discriminator: omit (or `false`) for custom scores. Required `true` for evaluation scores.
  - CreateEvaluationScoreBody — Internal, don't use
    - `simulationId` string, nullable — Simulation this score is tied to, if any. `null` (default) when not part of a simulation.
    - `value` number, required — Normalized score value in [0, 1]. Higher = better.
    - `passed` boolean, required — Whether the scored output passes the evaluator's bar.
    - `feedback` string, required — Free-text feedback explaining the score.
    - `error` string, nullable — Generation error text, when score generation itself failed. `null` (default) for successful scores.
    - `duration` integer — Score generation duration in nanoseconds. `0` for externally-computed scores.
    - `tokens` integer — LLM tokens consumed generating the score, if any. `0` for externally-computed scores.
    - `cost` integer — Score cost in microcents (100,000,000 per USD). `0` for externally-computed scores.
    - `trace` union, required — Target trace. Either an explicit id or a filter set matching exactly one trace.
      - object
        - `by` 'id', required — Match a single trace by its identifier. Pair with `id`.
        - `id` string, required — 32-character trace identifier.
      - object
        - `by` 'filters', required — Match a single trace by a filter set. Pair with `filters`; exactly one trace must match.
        - `filters` FilterSet, required — Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set.
    - `_evaluation` true, required — Discriminator: `true` flags the body as an evaluation score (internal); `false`/omit for custom.
    - `sourceId` string, required — CUID of the evaluation that produced this score.
    - `metadata` EvaluationScoreMetadata, required — Evaluation-specific metadata.
      - `evaluationHash` string, required — Hash of the evaluation script that produced this score; lets the platform track which version generated it.

## Response `201`

Score created

- union
  - CustomScoreResponse
    - `id` string, required — Stable score identifier.
    - `organizationId` string, required — Organization that owns this score.
    - `projectId` string, required — Project this score lives in.
    - `sessionId` string, nullable, required — Session id lifted from the trace, when set. `null` when the trace has no session.
    - `traceId` string, nullable, required — Identifier of the scored trace.
    - `spanId` string, nullable, required — Span the score pins to. Defaults to the trace's last LLM-completion span.
    - `simulationId` string, nullable, required — Simulation reference, if any.
    - `signalId` string, nullable, required — Signal this score contributes to, if any.
    - `value` number, required — Normalized score value in [0, 1].
    - `passed` boolean, required — Whether the score marks the output as passing.
    - `feedback` string, required — Free-text feedback explaining the score.
    - `error` string, nullable, required — Generation error text, when score generation itself errored. `null` for successful scores.
    - `errored` boolean, required — `true` when the score could not be generated successfully.
    - `duration` integer, required — Score generation duration in nanoseconds.
    - `tokens` integer, required — LLM tokens consumed generating the score.
    - `cost` integer, required — Score cost in microcents (100,000,000 per USD).
    - `draftedAt` string, date-time, nullable, required — ISO-8601 timestamp while the score is awaiting human confirmation. `null` for published / system scores.
    - `annotatorId` string, nullable, required — User who authored the score, if any.
    - `createdAt` string, date-time, required — ISO-8601 timestamp at which the score was created.
    - `updatedAt` string, date-time, required — ISO-8601 timestamp of the last metadata update.
    - `source` 'custom', required — Discriminator. `"custom"` denotes a user-supplied score.
    - `sourceId` string, required — User-supplied tag identifying the score's origin (echoed from the request).
    - `metadata` object, required — Arbitrary user-supplied metadata persisted alongside the score.
  - EvaluationScoreResponse
    - `id` string, required — Stable score identifier.
    - `organizationId` string, required — Organization that owns this score.
    - `projectId` string, required — Project this score lives in.
    - `sessionId` string, nullable, required — Session id lifted from the trace, when set. `null` when the trace has no session.
    - `traceId` string, nullable, required — Identifier of the scored trace.
    - `spanId` string, nullable, required — Span the score pins to. Defaults to the trace's last LLM-completion span.
    - `simulationId` string, nullable, required — Simulation reference, if any.
    - `signalId` string, nullable, required — Signal this score contributes to, if any.
    - `value` number, required — Normalized score value in [0, 1].
    - `passed` boolean, required — Whether the score marks the output as passing.
    - `feedback` string, required — Free-text feedback explaining the score.
    - `error` string, nullable, required — Generation error text, when score generation itself errored. `null` for successful scores.
    - `errored` boolean, required — `true` when the score could not be generated successfully.
    - `duration` integer, required — Score generation duration in nanoseconds.
    - `tokens` integer, required — LLM tokens consumed generating the score.
    - `cost` integer, required — Score cost in microcents (100,000,000 per USD).
    - `draftedAt` string, date-time, nullable, required — ISO-8601 timestamp while the score is awaiting human confirmation. `null` for published / system scores.
    - `annotatorId` string, nullable, required — User who authored the score, if any.
    - `createdAt` string, date-time, required — ISO-8601 timestamp at which the score was created.
    - `updatedAt` string, date-time, required — ISO-8601 timestamp of the last metadata update.
    - `source` 'evaluation', required — Discriminator. `"evaluation"` denotes a platform-generated evaluation score.
    - `sourceId` string, required — CUID of the evaluation that produced this score.
    - `metadata` EvaluationScoreMetadata, required — Evaluation-specific metadata.
      - `evaluationHash` string, required — Hash of the evaluation script that produced this score; lets the platform track which version generated it.

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/latitude-dev/apis/latitude.md) · [All operations](https://skmtc.net/latitude-dev/apis/latitude/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/latitude-dev/latitude/revisions/a0bf72a85607/schema)