Skip to main content
POST
/
api
/
v0
/
evaluate
Evaluation
curl --request POST \
  --url https://agents.graphy.dev/api/v0/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "type": "column",
    "data": {
      "columns": [
        {
          "key": "product",
          "label": "Product"
        },
        {
          "key": "revenue",
          "label": "Revenue"
        }
      ],
      "rows": [
        {
          "product": "Widget A",
          "revenue": 4200
        },
        {
          "product": "Widget B",
          "revenue": 3100
        },
        {
          "product": "Widget C",
          "revenue": 5600
        }
      ]
    }
  },
  "metadata": {
    "callId": "req-evaluate-1"
  }
}
'
{
  "ranking": [
    {
      "rank": 123,
      "score": 123,
      "factors": [
        {
          "label": "<string>",
          "weight": 123,
          "reason": "<string>"
        }
      ]
    }
  ]
}
Score how well every chart type fits a dataset. Evaluation is deterministic — a rule-based scorer with no language model — so it returns a single result and uses no tokens. Send a GraphConfig, receive a ranked list of chart types via Server-Sent Events.

​
Request body

Send a GraphConfig in config. Only config.data is scored — the chart type, styling, and annotations are ignored. Optionally pass a chartFamily hint (comparison, relationship, distribution, composition) to bias the ranking toward that family.

​
Response

The response is a Server-Sent Events stream. See SSE Format for parsing details. Evaluation is deterministic, so there are no progress events — the result arrives in a single complete event. 
event: complete
data: {"ranking":[{"rank":1,"type":"bar","score":0.82,"verdict":"ok","factors":[{"kind":"pro","label":"Categorical x-axis","weight":0.3,"reason":"One categorical dimension maps cleanly to bars"}]}]}
Final response data: 
interface EvaluateResponse {
  ranking: ChartFitEntry[];
}

interface ChartFitEntry {
  rank: number;
  type: AiChartType;
  score: number;
  verdict: 'ok' | 'disqualified';
  factors: ChartFitFactor[];
}
See the SDK Evaluation page for the full ChartFitEntry and ChartFitFactor field reference.

​
HTTP Status Codes

StatusDescription
200Success (stream begins)
400Invalid request body
401Invalid or missing API key
429Rate limit exceeded
500Internal server error
Errors may also arrive as SSE events within a 200 response — for example, a dataset with no plottable columns. See Error Codes.

Authorizations

​
Authorization
string
header
required

Your Graphy API key

Body

application/json

Deterministic evaluation reads only config.data and the optional chartFamily — there is no userPrompt.

​
config
object
required

The graph configuration object used to render charts. See Graph Config Schema for the complete reference.

​
chartFamily
enum<string>

Optional Abela chart-family hint. When set, chart types in that family get a fit bonus.

Available options:
comparison,
relationship,
distribution,
composition
​
metadata
object

Optional tracking information for requests

Response

SSE stream with a single completion event

SSE event name is "complete". Evaluation emits no progress events.

​
ranking
object[]
required

Every supported chart type, scored and ranked by fit (best first).