Run span-01 | Respan Docs

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": "span-01-free",
  "respan_params": {
    "customer_identifier": "acme-1042"
  }
}'

{
  "model": "span-01-free",
  "results": [
    {
      "id": "frustrated",
      "p_present": 0.4459707,
      "p_absent": 0.53500557,
      "p_not_observable": 0.019023689
    },
    {
      "id": "apology",
      "p_present": 0.9433637,
      "p_absent": 0.04003837,
      "p_not_observable": 0.016597953
    }
  ],
  "usage": {
    "input_tokens": 39
  }
}

Run inference with Span-01, Respan’s first-party classification model for agent traces. Provide an interaction in span and plain-language definitions in behaviors. Your application can use the model’s predictions for evaluations, guardrails, routing, and monitoring.

For each definition, the model returns the probabilities that it is present, absent, or not observable; the three probabilities sum to approximately 1. The example classifies a support interaction for user frustration and an assistant apology. Replace those definitions to apply the model to your own use case.

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 interaction to classify: preceding messages in input and the target turn 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 span-01-free

Use span-01-free or span-01-pro. Omit for span-01-free.

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 model 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. The example is the captured response to the request shown.

modelenum

The model used for inference.

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