Skip to content
sgp
API Reference
Span Assessments

List span or trace assessments

span_assessments.list(SpanAssessmentListParams**kwargs) -> 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.

ParametersExpand Collapse
assessment_type: Optional[AssessmentType]

Filter by assessment type

One of the following:
"comment"
"rating"
"approval"
"rubric"
"metadata"
"overwrite"
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.

ReturnsExpand Collapse
class SpanAssessment: …

Response model for span assessment

assessment_id: str

Unique identifier for the assessment

assessment_type: AssessmentType

Type of assessment

One of the following:
"comment"
"rating"
"approval"
"rubric"
"metadata"
"overwrite"
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)

One of the following:
"approved"
"rejected"
comment: Optional[str]

Raw text feedback

created_at: Optional[datetime]

When this assessment was created

formatdate-time
metadata: Optional[Dict[str, object]]

Arbitrary JSON object for additional data

object: Optional[Literal["span.assessment"]]
overwrite: Optional[Dict[str, object]]

User corrections to span output

rating: Optional[int]

Numerical rating (1-5)

maximum5
minimum1
rubric: Optional[Dict[str, str]]

Rule key-value pairs for rubric evaluation

updated_at: Optional[datetime]

When this assessment was last updated

formatdate-time

List span or trace assessments

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)
{
  "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"
}
Returns Examples
{
  "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"
}