# Span Assessments

## Create span assessment

`client.SpanAssessments.New(ctx, body) (*SpanAssessment, error)`

**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

- `body SpanAssessmentNewParams`

  - `AssessmentType param.Field[AssessmentType]`

    Type of assessment

  - `TraceID param.Field[string]`

    The ID of the trace this assessment is attached to

  - `Approval param.Field[ApprovalStatus]`

    Approval status (approved/rejected)

  - `Comment param.Field[string]`

    Raw text feedback

  - `Metadata param.Field[map[string, any]]`

    Arbitrary JSON object for additional data

  - `Overwrite param.Field[map[string, any]]`

    User corrections to span output

  - `Rating param.Field[int64]`

    Numerical rating (1-5)

  - `Rubric param.Field[map[string, string]]`

    Rule key-value pairs for rubric evaluation

  - `SpanID param.Field[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

- `type SpanAssessment struct{…}`

  Response model for span assessment

  - `AssessmentID string`

    Unique identifier for the assessment

  - `AssessmentType AssessmentType`

    Type of assessment

    - `const AssessmentTypeComment AssessmentType = "comment"`

    - `const AssessmentTypeRating AssessmentType = "rating"`

    - `const AssessmentTypeApproval AssessmentType = "approval"`

    - `const AssessmentTypeRubric AssessmentType = "rubric"`

    - `const AssessmentTypeMetadata AssessmentType = "metadata"`

    - `const AssessmentTypeOverwrite AssessmentType = "overwrite"`

  - `CreatedBy string`

    User who submitted the assessment

  - `SpanID string`

    The span this assessment is attached to

  - `TraceID string`

    The trace this assessment is attached to

  - `AccountID string`

    Account this assessment belongs to

  - `Approval ApprovalStatus`

    Approval status (approved/rejected)

    - `const ApprovalStatusApproved ApprovalStatus = "approved"`

    - `const ApprovalStatusRejected ApprovalStatus = "rejected"`

  - `Comment string`

    Raw text feedback

  - `CreatedAt Time`

    When this assessment was created

  - `Metadata map[string, any]`

    Arbitrary JSON object for additional data

  - `Object SpanAssessmentObject`

    - `const SpanAssessmentObjectSpanAssessment SpanAssessmentObject = "span.assessment"`

  - `Overwrite map[string, any]`

    User corrections to span output

  - `Rating int64`

    Numerical rating (1-5)

  - `Rubric map[string, string]`

    Rule key-value pairs for rubric evaluation

  - `UpdatedAt Time`

    When this assessment was last updated

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  spanAssessment, err := client.SpanAssessments.New(context.TODO(), sgpdev.SpanAssessmentNewParams{
    AssessmentType: sgpdev.AssessmentTypeComment,
    TraceID: "trace_id",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", spanAssessment.AssessmentID)
}
```

#### 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

`client.SpanAssessments.Get(ctx, spanAssessmentID) (*SpanAssessment, error)`

**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

- `spanAssessmentID string`

### Returns

- `type SpanAssessment struct{…}`

  Response model for span assessment

  - `AssessmentID string`

    Unique identifier for the assessment

  - `AssessmentType AssessmentType`

    Type of assessment

    - `const AssessmentTypeComment AssessmentType = "comment"`

    - `const AssessmentTypeRating AssessmentType = "rating"`

    - `const AssessmentTypeApproval AssessmentType = "approval"`

    - `const AssessmentTypeRubric AssessmentType = "rubric"`

    - `const AssessmentTypeMetadata AssessmentType = "metadata"`

    - `const AssessmentTypeOverwrite AssessmentType = "overwrite"`

  - `CreatedBy string`

    User who submitted the assessment

  - `SpanID string`

    The span this assessment is attached to

  - `TraceID string`

    The trace this assessment is attached to

  - `AccountID string`

    Account this assessment belongs to

  - `Approval ApprovalStatus`

    Approval status (approved/rejected)

    - `const ApprovalStatusApproved ApprovalStatus = "approved"`

    - `const ApprovalStatusRejected ApprovalStatus = "rejected"`

  - `Comment string`

    Raw text feedback

  - `CreatedAt Time`

    When this assessment was created

  - `Metadata map[string, any]`

    Arbitrary JSON object for additional data

  - `Object SpanAssessmentObject`

    - `const SpanAssessmentObjectSpanAssessment SpanAssessmentObject = "span.assessment"`

  - `Overwrite map[string, any]`

    User corrections to span output

  - `Rating int64`

    Numerical rating (1-5)

  - `Rubric map[string, string]`

    Rule key-value pairs for rubric evaluation

  - `UpdatedAt Time`

    When this assessment was last updated

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  spanAssessment, err := client.SpanAssessments.Get(context.TODO(), "span_assessment_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", spanAssessment.AssessmentID)
}
```

#### 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

`client.SpanAssessments.List(ctx, query) (*APIListPage[SpanAssessment], error)`

**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

- `query SpanAssessmentListParams`

  - `AssessmentType param.Field[AssessmentType]`

    Filter by assessment type

  - `SpanID param.Field[string]`

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

  - `TraceID param.Field[string]`

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

### Returns

- `type SpanAssessment struct{…}`

  Response model for span assessment

  - `AssessmentID string`

    Unique identifier for the assessment

  - `AssessmentType AssessmentType`

    Type of assessment

    - `const AssessmentTypeComment AssessmentType = "comment"`

    - `const AssessmentTypeRating AssessmentType = "rating"`

    - `const AssessmentTypeApproval AssessmentType = "approval"`

    - `const AssessmentTypeRubric AssessmentType = "rubric"`

    - `const AssessmentTypeMetadata AssessmentType = "metadata"`

    - `const AssessmentTypeOverwrite AssessmentType = "overwrite"`

  - `CreatedBy string`

    User who submitted the assessment

  - `SpanID string`

    The span this assessment is attached to

  - `TraceID string`

    The trace this assessment is attached to

  - `AccountID string`

    Account this assessment belongs to

  - `Approval ApprovalStatus`

    Approval status (approved/rejected)

    - `const ApprovalStatusApproved ApprovalStatus = "approved"`

    - `const ApprovalStatusRejected ApprovalStatus = "rejected"`

  - `Comment string`

    Raw text feedback

  - `CreatedAt Time`

    When this assessment was created

  - `Metadata map[string, any]`

    Arbitrary JSON object for additional data

  - `Object SpanAssessmentObject`

    - `const SpanAssessmentObjectSpanAssessment SpanAssessmentObject = "span.assessment"`

  - `Overwrite map[string, any]`

    User corrections to span output

  - `Rating int64`

    Numerical rating (1-5)

  - `Rubric map[string, string]`

    Rule key-value pairs for rubric evaluation

  - `UpdatedAt Time`

    When this assessment was last updated

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  page, err := client.SpanAssessments.List(context.TODO(), sgpdev.SpanAssessmentListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### 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

`client.SpanAssessments.Update(ctx, spanAssessmentID, body) (*SpanAssessment, error)`

**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

- `spanAssessmentID string`

- `body SpanAssessmentUpdateParams`

  - `Approval param.Field[ApprovalStatus]`

    Approval status (approved/rejected)

  - `AssessmentType param.Field[AssessmentType]`

    Type of assessment

  - `Comment param.Field[string]`

    Raw text feedback

  - `Metadata param.Field[map[string, any]]`

    Arbitrary JSON object for additional data

  - `Overwrite param.Field[map[string, any]]`

    User corrections to span output

  - `Rating param.Field[int64]`

    Numerical rating (1-5)

  - `Rubric param.Field[map[string, string]]`

    Rule key-value pairs for rubric evaluation

### Returns

- `type SpanAssessment struct{…}`

  Response model for span assessment

  - `AssessmentID string`

    Unique identifier for the assessment

  - `AssessmentType AssessmentType`

    Type of assessment

    - `const AssessmentTypeComment AssessmentType = "comment"`

    - `const AssessmentTypeRating AssessmentType = "rating"`

    - `const AssessmentTypeApproval AssessmentType = "approval"`

    - `const AssessmentTypeRubric AssessmentType = "rubric"`

    - `const AssessmentTypeMetadata AssessmentType = "metadata"`

    - `const AssessmentTypeOverwrite AssessmentType = "overwrite"`

  - `CreatedBy string`

    User who submitted the assessment

  - `SpanID string`

    The span this assessment is attached to

  - `TraceID string`

    The trace this assessment is attached to

  - `AccountID string`

    Account this assessment belongs to

  - `Approval ApprovalStatus`

    Approval status (approved/rejected)

    - `const ApprovalStatusApproved ApprovalStatus = "approved"`

    - `const ApprovalStatusRejected ApprovalStatus = "rejected"`

  - `Comment string`

    Raw text feedback

  - `CreatedAt Time`

    When this assessment was created

  - `Metadata map[string, any]`

    Arbitrary JSON object for additional data

  - `Object SpanAssessmentObject`

    - `const SpanAssessmentObjectSpanAssessment SpanAssessmentObject = "span.assessment"`

  - `Overwrite map[string, any]`

    User corrections to span output

  - `Rating int64`

    Numerical rating (1-5)

  - `Rubric map[string, string]`

    Rule key-value pairs for rubric evaluation

  - `UpdatedAt Time`

    When this assessment was last updated

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  spanAssessment, err := client.SpanAssessments.Update(
    context.TODO(),
    "span_assessment_id",
    sgpdev.SpanAssessmentUpdateParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", spanAssessment.AssessmentID)
}
```

#### 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

`client.SpanAssessments.Delete(ctx, spanAssessmentID) (*SpanAssessmentDeleteResponse, error)`

**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

- `spanAssessmentID string`

### Returns

- `type SpanAssessmentDeleteResponse struct{…}`

  - `ID string`

  - `Deleted bool`

  - `Object SpanAssessmentDeleteResponseObject`

    - `const SpanAssessmentDeleteResponseObjectSpanAssessment SpanAssessmentDeleteResponseObject = "span.assessment"`

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  spanAssessment, err := client.SpanAssessments.Delete(context.TODO(), "span_assessment_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", spanAssessment.ID)
}
```

#### Response

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

## Domain Types

### Approval Status

- `type ApprovalStatus string`

  Status options for approval assessments

  - `const ApprovalStatusApproved ApprovalStatus = "approved"`

  - `const ApprovalStatusRejected ApprovalStatus = "rejected"`

### Assessment Type

- `type AssessmentType string`

  Types of assessments that can be provided

  - `const AssessmentTypeComment AssessmentType = "comment"`

  - `const AssessmentTypeRating AssessmentType = "rating"`

  - `const AssessmentTypeApproval AssessmentType = "approval"`

  - `const AssessmentTypeRubric AssessmentType = "rubric"`

  - `const AssessmentTypeMetadata AssessmentType = "metadata"`

  - `const AssessmentTypeOverwrite AssessmentType = "overwrite"`

### Span Assessment

- `type SpanAssessment struct{…}`

  Response model for span assessment

  - `AssessmentID string`

    Unique identifier for the assessment

  - `AssessmentType AssessmentType`

    Type of assessment

    - `const AssessmentTypeComment AssessmentType = "comment"`

    - `const AssessmentTypeRating AssessmentType = "rating"`

    - `const AssessmentTypeApproval AssessmentType = "approval"`

    - `const AssessmentTypeRubric AssessmentType = "rubric"`

    - `const AssessmentTypeMetadata AssessmentType = "metadata"`

    - `const AssessmentTypeOverwrite AssessmentType = "overwrite"`

  - `CreatedBy string`

    User who submitted the assessment

  - `SpanID string`

    The span this assessment is attached to

  - `TraceID string`

    The trace this assessment is attached to

  - `AccountID string`

    Account this assessment belongs to

  - `Approval ApprovalStatus`

    Approval status (approved/rejected)

    - `const ApprovalStatusApproved ApprovalStatus = "approved"`

    - `const ApprovalStatusRejected ApprovalStatus = "rejected"`

  - `Comment string`

    Raw text feedback

  - `CreatedAt Time`

    When this assessment was created

  - `Metadata map[string, any]`

    Arbitrary JSON object for additional data

  - `Object SpanAssessmentObject`

    - `const SpanAssessmentObjectSpanAssessment SpanAssessmentObject = "span.assessment"`

  - `Overwrite map[string, any]`

    User corrections to span output

  - `Rating int64`

    Numerical rating (1-5)

  - `Rubric map[string, string]`

    Rule key-value pairs for rubric evaluation

  - `UpdatedAt Time`

    When this assessment was last updated