Documentation | Span Assessments

Span Assessments

SpanAssessmentsResource

Methods

client.span_assessments.create() ->

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. At most one user per span may hold an overwrite assessment, so creating an overwrite for a span another user has already overwritten returns 409. Use the list endpoint to read a span's or trace's existing assessments.

client.span_assessments.retrieve() ->

SpanAssessment

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.

client.span_assessments.list() -> SyncAPIListPage[

SpanAssessment

]

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.

Parameters

assessment_type: Optional[

AssessmentType

]

Filter by assessment type

span_id: Optional[str]

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

trace_id: Optional[str]

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

Returns

SpanAssessment

assessment_id: str

Unique identifier for the assessment

assessment_type:

AssessmentType

Type of assessment

created_by: str

User who submitted the assessment

span_id: str

The span this assessment is attached to

trace_id: str

The trace this assessment is attached to

account_id: Optional[str]

Account this assessment belongs to

approval: Optional[ApprovalStatus]

Approval status (approved/rejected)

comment: Optional[str]

Raw text feedback

created_at: Optional[datetime]

(format: date-time)

When this assessment was created

metadata: Optional[Dict[str,

object

]]

Arbitrary JSON object for additional data

object: Optional[Literal["span.assessment"]]

(default: "span.assessment")

overwrite: Optional[Dict[str,

object

]]

User corrections to span output

rating: Optional[int]

(maximum: 5, minimum: 1)

Numerical rating (1-5)

rubric: Optional[Dict[str, str]]

Rule key-value pairs for rubric evaluation

updated_at: Optional[datetime]

(format: date-time)

When this assessment was last updated

Request example

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
page = client.span_assessments.list()
page = page.items[0]
print(page.assessment_id)

200Example

{
  "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"
}

client.span_assessments.update(, ) ->

SpanAssessment

patch/v5/span-assessments/{span_assessment_id}

Update the content of an existing span assessment.

Only the assessment's original creator 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.

client.span_assessments.delete() ->

SpanAssessmentDeleteResponse

delete/v5/span-assessments/{span_assessment_id}

Permanently delete a span assessment by its identifier.

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.

Domain types

Literal["approved", "rejected"]

Status options for approval assessments

Literal["comment", "rating", "approval", "rubric", "metadata", "overwrite"]

Types of assessments that can be provided

class SpanAssessment: ...

Response model for span assessment

class SpanAssessmentDeleteResponse: ...