# Span Assessments

## Create span assessment

**post** `/v5/span-assessments`

Attach a new assessment to a span within a trace.

A span assessment records feedback on a single span's output. Its
assessment_type selects one of comment, rating (an integer 1-5), approval
(approved or rejected), rubric (key-value rule pairs), metadata (arbitrary
JSON), or overwrite (a corrected span output), and exactly the content field
matching that type must be supplied; a free-text comment may additionally
accompany any type. trace_id is required, while span_id is optional and, when
omitted, the assessment is attached to the trace's root span. The call returns
404 if the given span_id and trace_id do not identify an existing span, or if
no root span is found for the trace. Creating an overwrite for a span that
already holds a live overwrite returns 409, whether that overwrite is yours or
another user's. Update or delete the existing one instead. Use the list
endpoint to read a span's or trace's existing assessments.

### Body Parameters

- `assessment_type: AssessmentType`

  Type of assessment

  - `"comment"`

  - `"rating"`

  - `"approval"`

  - `"rubric"`

  - `"metadata"`

  - `"overwrite"`

- `trace_id: string`

  The ID of the trace this assessment is attached to

- `approval: optional ApprovalStatus`

  Approval status (approved/rejected)

  - `"approved"`

  - `"rejected"`

- `comment: optional string`

  Raw text feedback

- `metadata: optional map[unknown]`

  Arbitrary JSON object for additional data

- `overwrite: optional map[unknown]`

  User corrections to span output

- `rating: optional number`

  Numerical rating (1-5)

- `rubric: optional map[string]`

  Rule key-value pairs for rubric evaluation

- `span_id: optional string`

  The ID of the span this assessment is attached to. If omitted, the assessment is attached to the root span of the trace.

### Returns

- `SpanAssessment object { assessment_id, assessment_type, created_by, 12 more }`

  Response model for span assessment

  - `assessment_id: string`

    Unique identifier for the assessment

  - `assessment_type: AssessmentType`

    Type of assessment

    - `"comment"`

    - `"rating"`

    - `"approval"`

    - `"rubric"`

    - `"metadata"`

    - `"overwrite"`

  - `created_by: string`

    User who submitted the assessment

  - `span_id: string`

    The span this assessment is attached to

  - `trace_id: string`

    The trace this assessment is attached to

  - `account_id: optional string`

    Account this assessment belongs to

  - `approval: optional ApprovalStatus`

    Approval status (approved/rejected)

    - `"approved"`

    - `"rejected"`

  - `comment: optional string`

    Raw text feedback

  - `created_at: optional string`

    When this assessment was created

  - `metadata: optional map[unknown]`

    Arbitrary JSON object for additional data

  - `object: optional "span.assessment"`

    - `"span.assessment"`

  - `overwrite: optional map[unknown]`

    User corrections to span output

  - `rating: optional number`

    Numerical rating (1-5)

  - `rubric: optional map[string]`

    Rule key-value pairs for rubric evaluation

  - `updated_at: optional string`

    When this assessment was last updated

### Example

```http
curl https://api.egp.scale.com/v5/span-assessments \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{
          "assessment_type": "comment",
          "trace_id": "trace_id"
        }'
```

#### Response

```json
{
  "assessment_id": "assessment_id",
  "assessment_type": "comment",
  "created_by": "created_by",
  "span_id": "span_id",
  "trace_id": "trace_id",
  "account_id": "account_id",
  "approval": "approved",
  "comment": "comment",
  "created_at": "2019-12-27T18:11:19.117Z",
  "metadata": {
    "foo": "bar"
  },
  "object": "span.assessment",
  "overwrite": {
    "foo": "bar"
  },
  "rating": 1,
  "rubric": {
    "foo": "string"
  },
  "updated_at": "2019-12-27T18:11:19.117Z"
}
```

## Get span assessment by ID

**get** `/v5/span-assessments/{span_assessment_id}`

Retrieve a single span assessment by its identifier.

Returns the assessment's type and content fields, the span and trace it is
attached to, and the identity that created it. Returns 404 if no assessment
with that id exists for the caller's account. Use the list endpoint instead
when you have a span or trace id rather than an assessment id.

### Path Parameters

- `span_assessment_id: string`

### Returns

- `SpanAssessment object { assessment_id, assessment_type, created_by, 12 more }`

  Response model for span assessment

  - `assessment_id: string`

    Unique identifier for the assessment

  - `assessment_type: AssessmentType`

    Type of assessment

    - `"comment"`

    - `"rating"`

    - `"approval"`

    - `"rubric"`

    - `"metadata"`

    - `"overwrite"`

  - `created_by: string`

    User who submitted the assessment

  - `span_id: string`

    The span this assessment is attached to

  - `trace_id: string`

    The trace this assessment is attached to

  - `account_id: optional string`

    Account this assessment belongs to

  - `approval: optional ApprovalStatus`

    Approval status (approved/rejected)

    - `"approved"`

    - `"rejected"`

  - `comment: optional string`

    Raw text feedback

  - `created_at: optional string`

    When this assessment was created

  - `metadata: optional map[unknown]`

    Arbitrary JSON object for additional data

  - `object: optional "span.assessment"`

    - `"span.assessment"`

  - `overwrite: optional map[unknown]`

    User corrections to span output

  - `rating: optional number`

    Numerical rating (1-5)

  - `rubric: optional map[string]`

    Rule key-value pairs for rubric evaluation

  - `updated_at: optional string`

    When this assessment was last updated

### Example

```http
curl https://api.egp.scale.com/v5/span-assessments/$SPAN_ASSESSMENT_ID \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "assessment_id": "assessment_id",
  "assessment_type": "comment",
  "created_by": "created_by",
  "span_id": "span_id",
  "trace_id": "trace_id",
  "account_id": "account_id",
  "approval": "approved",
  "comment": "comment",
  "created_at": "2019-12-27T18:11:19.117Z",
  "metadata": {
    "foo": "bar"
  },
  "object": "span.assessment",
  "overwrite": {
    "foo": "bar"
  },
  "rating": 1,
  "rubric": {
    "foo": "string"
  },
  "updated_at": "2019-12-27T18:11:19.117Z"
}
```

## List span or trace assessments

**get** `/v5/span-assessments`

Return the assessments attached to a given span or trace.

Results are scoped to the caller's account. Exactly one of span_id or
trace_id must be supplied as a query parameter, and a request providing
neither returns 400. Filtering by trace_id returns assessments across every
span of that trace, whereas span_id returns only that span's assessments; an
optional assessment_type narrows the results to a single type. Use the
get-by-id endpoint when you already have a specific assessment id.

### Query Parameters

- `assessment_type: optional AssessmentType`

  Filter by assessment type

  - `"comment"`

  - `"rating"`

  - `"approval"`

  - `"rubric"`

  - `"metadata"`

  - `"overwrite"`

- `span_id: optional string`

  Filter by span ID. Either span_id or trace_id must be provided as a query parameter.

- `trace_id: optional string`

  Filter by trace ID. Either span_id or trace_id must be provided as a query parameter.

### Returns

- `items: array of SpanAssessment`

  - `assessment_id: string`

    Unique identifier for the assessment

  - `assessment_type: AssessmentType`

    Type of assessment

    - `"comment"`

    - `"rating"`

    - `"approval"`

    - `"rubric"`

    - `"metadata"`

    - `"overwrite"`

  - `created_by: string`

    User who submitted the assessment

  - `span_id: string`

    The span this assessment is attached to

  - `trace_id: string`

    The trace this assessment is attached to

  - `account_id: optional string`

    Account this assessment belongs to

  - `approval: optional ApprovalStatus`

    Approval status (approved/rejected)

    - `"approved"`

    - `"rejected"`

  - `comment: optional string`

    Raw text feedback

  - `created_at: optional string`

    When this assessment was created

  - `metadata: optional map[unknown]`

    Arbitrary JSON object for additional data

  - `object: optional "span.assessment"`

    - `"span.assessment"`

  - `overwrite: optional map[unknown]`

    User corrections to span output

  - `rating: optional number`

    Numerical rating (1-5)

  - `rubric: optional map[string]`

    Rule key-value pairs for rubric evaluation

  - `updated_at: optional string`

    When this assessment was last updated

- `object: optional "list"`

  - `"list"`

### Example

```http
curl https://api.egp.scale.com/v5/span-assessments \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "items": [
    {
      "assessment_id": "assessment_id",
      "assessment_type": "comment",
      "created_by": "created_by",
      "span_id": "span_id",
      "trace_id": "trace_id",
      "account_id": "account_id",
      "approval": "approved",
      "comment": "comment",
      "created_at": "2019-12-27T18:11:19.117Z",
      "metadata": {
        "foo": "bar"
      },
      "object": "span.assessment",
      "overwrite": {
        "foo": "bar"
      },
      "rating": 1,
      "rubric": {
        "foo": "string"
      },
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ],
  "object": "list"
}
```

## Update span assessment

**patch** `/v5/span-assessments/{span_assessment_id}`

Update the content of an existing span assessment.

Only the assessment's original creator, or an account admin or manager, may
update it; a request from any other identity returns 403. Supplied fields
overwrite the stored values and
the merged result is re-validated against the assessment's type, so the
content must stay consistent with assessment_type (the matching content field
present and no conflicting fields set) or the call returns 422. The span and
trace an assessment is attached to cannot be changed through this endpoint.
Returns 404 if no assessment with that id exists for the caller's account.

### Path Parameters

- `span_assessment_id: string`

### Body Parameters

- `approval: optional ApprovalStatus`

  Approval status (approved/rejected)

  - `"approved"`

  - `"rejected"`

- `assessment_type: optional AssessmentType`

  Type of assessment

  - `"comment"`

  - `"rating"`

  - `"approval"`

  - `"rubric"`

  - `"metadata"`

  - `"overwrite"`

- `comment: optional string`

  Raw text feedback

- `metadata: optional map[unknown]`

  Arbitrary JSON object for additional data

- `overwrite: optional map[unknown]`

  User corrections to span output

- `rating: optional number`

  Numerical rating (1-5)

- `rubric: optional map[string]`

  Rule key-value pairs for rubric evaluation

### Returns

- `SpanAssessment object { assessment_id, assessment_type, created_by, 12 more }`

  Response model for span assessment

  - `assessment_id: string`

    Unique identifier for the assessment

  - `assessment_type: AssessmentType`

    Type of assessment

    - `"comment"`

    - `"rating"`

    - `"approval"`

    - `"rubric"`

    - `"metadata"`

    - `"overwrite"`

  - `created_by: string`

    User who submitted the assessment

  - `span_id: string`

    The span this assessment is attached to

  - `trace_id: string`

    The trace this assessment is attached to

  - `account_id: optional string`

    Account this assessment belongs to

  - `approval: optional ApprovalStatus`

    Approval status (approved/rejected)

    - `"approved"`

    - `"rejected"`

  - `comment: optional string`

    Raw text feedback

  - `created_at: optional string`

    When this assessment was created

  - `metadata: optional map[unknown]`

    Arbitrary JSON object for additional data

  - `object: optional "span.assessment"`

    - `"span.assessment"`

  - `overwrite: optional map[unknown]`

    User corrections to span output

  - `rating: optional number`

    Numerical rating (1-5)

  - `rubric: optional map[string]`

    Rule key-value pairs for rubric evaluation

  - `updated_at: optional string`

    When this assessment was last updated

### Example

```http
curl https://api.egp.scale.com/v5/span-assessments/$SPAN_ASSESSMENT_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "x-api-key: $SGP_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "assessment_id": "assessment_id",
  "assessment_type": "comment",
  "created_by": "created_by",
  "span_id": "span_id",
  "trace_id": "trace_id",
  "account_id": "account_id",
  "approval": "approved",
  "comment": "comment",
  "created_at": "2019-12-27T18:11:19.117Z",
  "metadata": {
    "foo": "bar"
  },
  "object": "span.assessment",
  "overwrite": {
    "foo": "bar"
  },
  "rating": 1,
  "rubric": {
    "foo": "string"
  },
  "updated_at": "2019-12-27T18:11:19.117Z"
}
```

## Permanently delete span assessment

**delete** `/v5/span-assessments/{span_assessment_id}`

Permanently delete a span assessment by its identifier.

Only the assessment's original creator, or an account admin or manager, may
delete it; a request from any other identity returns 403. This is a hard
delete: the assessment row is removed rather than archived, so it cannot be
restored afterward. The response echoes the deleted assessment's id. Returns
404 if no assessment with that id exists for the caller's account.

### Path Parameters

- `span_assessment_id: string`

### Returns

- `id: string`

- `deleted: boolean`

- `object: optional "span.assessment"`

  - `"span.assessment"`

### Example

```http
curl https://api.egp.scale.com/v5/span-assessments/$SPAN_ASSESSMENT_ID \
    -X DELETE \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "id": "id",
  "deleted": true,
  "object": "span.assessment"
}
```

## Domain Types

### Approval Status

- `ApprovalStatus = "approved" or "rejected"`

  Status options for approval assessments

  - `"approved"`

  - `"rejected"`

### Assessment Type

- `AssessmentType = "comment" or "rating" or "approval" or 3 more`

  Types of assessments that can be provided

  - `"comment"`

  - `"rating"`

  - `"approval"`

  - `"rubric"`

  - `"metadata"`

  - `"overwrite"`

### Span Assessment

- `SpanAssessment object { assessment_id, assessment_type, created_by, 12 more }`

  Response model for span assessment

  - `assessment_id: string`

    Unique identifier for the assessment

  - `assessment_type: AssessmentType`

    Type of assessment

    - `"comment"`

    - `"rating"`

    - `"approval"`

    - `"rubric"`

    - `"metadata"`

    - `"overwrite"`

  - `created_by: string`

    User who submitted the assessment

  - `span_id: string`

    The span this assessment is attached to

  - `trace_id: string`

    The trace this assessment is attached to

  - `account_id: optional string`

    Account this assessment belongs to

  - `approval: optional ApprovalStatus`

    Approval status (approved/rejected)

    - `"approved"`

    - `"rejected"`

  - `comment: optional string`

    Raw text feedback

  - `created_at: optional string`

    When this assessment was created

  - `metadata: optional map[unknown]`

    Arbitrary JSON object for additional data

  - `object: optional "span.assessment"`

    - `"span.assessment"`

  - `overwrite: optional map[unknown]`

    User corrections to span output

  - `rating: optional number`

    Numerical rating (1-5)

  - `rubric: optional map[string]`

    Rule key-value pairs for rubric evaluation

  - `updated_at: optional string`

    When this assessment was last updated

### Span Assessment Delete Response

- `SpanAssessmentDeleteResponse object { id, deleted, object }`

  - `id: string`

  - `deleted: boolean`

  - `object: optional "span.assessment"`

    - `"span.assessment"`