# Span Assessments ## Create span assessment `span_assessments.create(SpanAssessmentCreateParams**kwargs) -> SpanAssessment` **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. ### Parameters - `assessment_type: AssessmentType` Type of assessment - `"comment"` - `"rating"` - `"approval"` - `"rubric"` - `"metadata"` - `"overwrite"` - `trace_id: str` The ID of the trace this assessment is attached to - `approval: Optional[ApprovalStatus]` Approval status (approved/rejected) - `"approved"` - `"rejected"` - `comment: Optional[str]` Raw text feedback - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation - `span_id: Optional[str]` The ID of the span this assessment is attached to. If omitted, the assessment is attached to the root span of the trace. ### Returns - `class SpanAssessment: …` Response model for span assessment - `assessment_id: str` Unique identifier for the assessment - `assessment_type: AssessmentType` Type of assessment - `"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) - `"approved"` - `"rejected"` - `comment: Optional[str]` Raw text feedback - `created_at: Optional[datetime]` When this assessment was created - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"` - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation - `updated_at: Optional[datetime]` When this assessment was last updated ### Example ```python 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 ) span_assessment = client.span_assessments.create( assessment_type="comment", trace_id="trace_id", ) print(span_assessment.assessment_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 `span_assessments.retrieve(strspan_assessment_id) -> 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. ### Parameters - `span_assessment_id: str` ### Returns - `class SpanAssessment: …` Response model for span assessment - `assessment_id: str` Unique identifier for the assessment - `assessment_type: AssessmentType` Type of assessment - `"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) - `"approved"` - `"rejected"` - `comment: Optional[str]` Raw text feedback - `created_at: Optional[datetime]` When this assessment was created - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"` - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation - `updated_at: Optional[datetime]` When this assessment was last updated ### Example ```python 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 ) span_assessment = client.span_assessments.retrieve( "span_assessment_id", ) print(span_assessment.assessment_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" } ``` ## 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. ### Parameters - `assessment_type: Optional[AssessmentType]` Filter by assessment type - `"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. ### Returns - `class SpanAssessment: …` Response model for span assessment - `assessment_id: str` Unique identifier for the assessment - `assessment_type: AssessmentType` Type of assessment - `"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) - `"approved"` - `"rejected"` - `comment: Optional[str]` Raw text feedback - `created_at: Optional[datetime]` When this assessment was created - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"` - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation - `updated_at: Optional[datetime]` When this assessment was last updated ### Example ```python 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) ``` #### 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 `span_assessments.update(strspan_assessment_id, SpanAssessmentUpdateParams**kwargs) -> SpanAssessment` **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. ### Parameters - `span_assessment_id: str` - `approval: Optional[ApprovalStatus]` Approval status (approved/rejected) - `"approved"` - `"rejected"` - `assessment_type: Optional[AssessmentType]` Type of assessment - `"comment"` - `"rating"` - `"approval"` - `"rubric"` - `"metadata"` - `"overwrite"` - `comment: Optional[str]` Raw text feedback - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation ### Returns - `class SpanAssessment: …` Response model for span assessment - `assessment_id: str` Unique identifier for the assessment - `assessment_type: AssessmentType` Type of assessment - `"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) - `"approved"` - `"rejected"` - `comment: Optional[str]` Raw text feedback - `created_at: Optional[datetime]` When this assessment was created - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"` - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation - `updated_at: Optional[datetime]` When this assessment was last updated ### Example ```python 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 ) span_assessment = client.span_assessments.update( span_assessment_id="span_assessment_id", ) print(span_assessment.assessment_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" } ``` ## Permanently delete span assessment `span_assessments.delete(strspan_assessment_id) -> SpanAssessmentDeleteResponse` **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. ### Parameters - `span_assessment_id: str` ### Returns - `class SpanAssessmentDeleteResponse: …` - `id: str` - `deleted: bool` - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"` ### Example ```python 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 ) span_assessment = client.span_assessments.delete( "span_assessment_id", ) print(span_assessment.id) ``` #### Response ```json { "id": "id", "deleted": true, "object": "span.assessment" } ``` ## Domain Types ### Approval Status - `Literal["approved", "rejected"]` Status options for approval assessments - `"approved"` - `"rejected"` ### Assessment Type - `Literal["comment", "rating", "approval", 3 more]` Types of assessments that can be provided - `"comment"` - `"rating"` - `"approval"` - `"rubric"` - `"metadata"` - `"overwrite"` ### Span Assessment - `class SpanAssessment: …` Response model for span assessment - `assessment_id: str` Unique identifier for the assessment - `assessment_type: AssessmentType` Type of assessment - `"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) - `"approved"` - `"rejected"` - `comment: Optional[str]` Raw text feedback - `created_at: Optional[datetime]` When this assessment was created - `metadata: Optional[Dict[str, object]]` Arbitrary JSON object for additional data - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"` - `overwrite: Optional[Dict[str, object]]` User corrections to span output - `rating: Optional[int]` Numerical rating (1-5) - `rubric: Optional[Dict[str, str]]` Rule key-value pairs for rubric evaluation - `updated_at: Optional[datetime]` When this assessment was last updated ### Span Assessment Delete Response - `class SpanAssessmentDeleteResponse: …` - `id: str` - `deleted: bool` - `object: Optional[Literal["span.assessment"]]` - `"span.assessment"`