Skip to navigation
Modelsspan-01

Quickstart

Score a conversation for escalation with one API call.
1

Get an API key

Create a key under API keys, then export it:

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
2

Send a request

curl https://api.respan.ai/api/v1/scores \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "span-01-free",
    "span": {
      "input": [
        { "role": "user", "content": "Please connect me to a person." }
      ],
      "output": {
        "role": "assistant",
        "content": "I will connect you to our support team."
      }
    },
    "behaviors": [
      {
        "id": "escalation",
        "definition": "the user wants a human/agent/representative, or the assistant says a human handoff is needed (not mere frustration or wanting a better answer)."
      }
    ]
  }'

span.input holds the prior messages. span.output is the turn being scored.

3

Read the response

{
  "model": "span-01-free",
  "results": [
    {
      "id": "escalation",
      "p_present": 0.729968,
      "p_absent": 0.25372452,
      "p_not_observable": 0.016307479
    }
  ],
  "usage": {
    "input_tokens": 51
  }
}

p_present is 0.73, so escalation is likely. p_absent is the probability it didn’t happen, and p_not_observable is the probability the span lacks the evidence to decide. The three sum to about 1.

4

Score your own data

  • Replace span.input and span.output with your conversation.
  • Add entries to behaviors. Each one needs an id and a definition, and all of them are scored in one pass.
  • Set model to span-01-pro for span-01. The default, span-01-free, is span-01 Lite.

For every request and response field, see the API reference.