Skip to content
sgp
API Reference
Span Assessments

Create span assessment

client.spanAssessments.create(SpanAssessmentCreateParams { assessment_type, trace_id, approval, 6 more } body, RequestOptionsoptions?): SpanAssessment { assessment_id, assessment_type, created_by, 12 more }
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.

ParametersExpand Collapse
body: SpanAssessmentCreateParams { assessment_type, trace_id, approval, 6 more }
assessment_type: AssessmentType

Type of assessment

One of the following:
"comment"
"rating"
"approval"
"rubric"
"metadata"
"overwrite"
trace_id: string

The ID of the trace this assessment is attached to

approval?: ApprovalStatus

Approval status (approved/rejected)

One of the following:
"approved"
"rejected"
comment?: string

Raw text feedback

metadata?: Record<string, unknown>

Arbitrary JSON object for additional data

overwrite?: Record<string, unknown>

User corrections to span output

rating?: number

Numerical rating (1-5)

maximum5
minimum1
rubric?: Record<string, string>

Rule key-value pairs for rubric evaluation

span_id?: string

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

ReturnsExpand Collapse
SpanAssessment { 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

One of the following:
"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?: string

Account this assessment belongs to

approval?: ApprovalStatus

Approval status (approved/rejected)

One of the following:
"approved"
"rejected"
comment?: string

Raw text feedback

created_at?: string

When this assessment was created

formatdate-time
metadata?: Record<string, unknown>

Arbitrary JSON object for additional data

object?: "span.assessment"
overwrite?: Record<string, unknown>

User corrections to span output

rating?: number

Numerical rating (1-5)

maximum5
minimum1
rubric?: Record<string, string>

Rule key-value pairs for rubric evaluation

updated_at?: string

When this assessment was last updated

formatdate-time

Create span assessment

import SGPClient from 'scale-gp';

const client = new SGPClient({
  accountID: 'My Account ID',
  apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted
});

const spanAssessment = await client.spanAssessments.create({
  assessment_type: 'comment',
  trace_id: 'trace_id',
});

console.log(spanAssessment.assessment_id);
{
  "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"
}
Returns Examples
{
  "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"
}