Score behaviors with Span-1

curl -X POST https://api.respan.ai/api/v1/scores \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "span": {
    "input": [
      {
        "role": "user",
        "content": "This is the third time my order is late."
      }
    ],
    "output": {
      "role": "assistant",
      "content": "I am sorry, let me check on that for you."
    }
  },
  "behaviors": [
    {
      "id": "frustrated",
      "definition": "The user expresses frustration or anger."
    },
    {
      "id": "apology",
      "definition": "The assistant apologizes for a problem."
    }
  ],
  "model": "lite",
  "respan_params": {
    "customer_identifier": "acme-1042"
  }
}'

{
  "model": "span-1-lite",
  "results": [
    {
      "id": "frustrated",
      "p_present": 0.87,
      "p_absent": 0.11,
      "p_not_observable": 0.02
    },
    {
      "id": "apology",
      "p_present": 0.96,
      "p_absent": 0.02,
      "p_not_observable": 0.02
    }
  ],
  "usage": {
    "input_tokens": 39
  }
}

In the example, a customer complains that their order is late, and the assistant apologizes:

span.input contains the customer’s message.
span.output contains the assistant’s reply.
behaviors defines two checks: frustrated checks whether the user expresses frustration, and apology checks whether the assistant apologizes. Each result uses the same id as its check.

The example response gives frustrated a p_present of 0.87 (87%) and apology a p_present of 0.96 (96%). For each check:

p_present is the probability that the behavior is present.
p_absent is the probability that it is absent.
p_not_observable is the probability that there is not enough evidence to judge.

These three probabilities sum to approximately 1. The example values are illustrative.

Use Span-1 to check a conversation for behaviors you describe in plain language. The endpoint returns probabilities showing whether each behavior is present, absent, or cannot be judged from the conversation. In the example, a customer complains that their order is late, and the assistant apologizes: - `span.input` contains the customer's message. - `span.output` contains the assistant's reply. - `behaviors` defines two checks: `frustrated` checks whether the user expresses frustration, and `apology` checks whether the assistant apologizes. Each result uses the same `id` as its check. The example response gives `frustrated` a `p_present` of **0.87 (87%)** and `apology` a `p_present` of **0.96 (96%)**. For each check: - `p_present` is the probability that the behavior is present. - `p_absent` is the probability that it is absent. - `p_not_observable` is the probability that there is not enough evidence to judge. These three probabilities sum to approximately 1. The example values are illustrative.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects an object.

spanobjectRequired

The conversation content to score: preceding messages in input and the turn being judged in output.

behaviorslist of objectsRequired

The rubric: one ID and plain-language definition per behavior. There is no per-request behavior-count cap. Definitions count toward usage.input_tokens.

modelstringOptionalDefaults to lite

Use lite or pro. Omit for lite. The aliases span-1-lite and span-1-pro are also accepted. Responses use the full model name.

respan_paramsobjectOptional

Optional Respan gateway parameters for logging and attribution. These are removed before the request reaches the scorer. See the Respan gateway parameters guide for other supported fields.

Response headers

X-Respan-Log-IdstringOptional

ID of the Respan request log. Use it to find the scoring call in your organization's logs. It may be absent when a request is rejected before a log is created.

Response

Behavior probabilities for the submitted span. Example values are illustrative and will vary with the content, rubric, and model.

modelenum

The full name of the model that scored the span, even when the request used lite or pro.

Allowed values:

resultslist of objects

One result per behavior, in the same order as the request. Match each result using its id.

usageobjectOptional

Token usage, when reported by the scorer. May be omitted if the scorer does not report token counts.

Errors

400

Bad Request Error

402

Payment Required Error

403

Forbidden Error

413

Content Too Large Error

422

Unprocessable Entity Error

424

Failed Dependency Error

429

Too Many Requests Error

503

Service Unavailable Error

504

Gateway Timeout Error

In the example, a customer complains that their order is late, and the assistant apologizes:

span.input contains the customer’s message.
span.output contains the assistant’s reply.
behaviors defines two checks: frustrated checks whether the user expresses frustration, and apology checks whether the assistant apologizes. Each result uses the same id as its check.

The example response gives frustrated a p_present of 0.87 (87%) and apology a p_present of 0.96 (96%). For each check:

p_present is the probability that the behavior is present.
p_absent is the probability that it is absent.
p_not_observable is the probability that there is not enough evidence to judge.

These three probabilities sum to approximately 1. The example values are illustrative.