> ## Documentation Index > Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt > Use this file to discover all available pages before exploring further. # Evaluation > Score how well every chart type fits a dataset. Deterministic — a rule-based scorer with no language model, so it returns a single result and uses no tokens. Only config.data is scored. The response is a Server-Sent Events (SSE) stream. Evaluation emits no progress events — the result arrives in a single complete event. 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](/agents/rest/sse) for parsing details. Evaluation is deterministic, so there are no `progress` events — the result arrives in a single `complete` event. ```text theme={null} 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:** ```typescript theme={null} interface EvaluateResponse { ranking: ChartFitEntry[]; } interface ChartFitEntry { rank: number; type: AiChartType; score: number; verdict: 'ok' | 'disqualified'; factors: ChartFitFactor[]; } ``` See the [SDK Evaluation page](/agents/sdk/evaluate) for the full `ChartFitEntry` and `ChartFitFactor` field reference. ## HTTP Status Codes | Status | Description | | ------ | -------------------------- | | 200 | Success (stream begins) | | 400 | Invalid request body | | 401 | Invalid or missing API key | | 429 | Rate limit exceeded | | 500 | Internal server error | Errors may also arrive as SSE events within a 200 response — for example, a dataset with no plottable columns. See [Error Codes](/agents/rest/errors). ## OpenAPI ````yaml POST /api/v0/evaluate openapi: 3.1.0 info: title: Graphy AI Agents API version: 0.1.0 description: AI-powered chart generation and modification API servers: - url: https://agents.graphy.dev description: Production security: - bearerAuth: [] paths: /api/v0/evaluate: post: tags: - Agents summary: Evaluation description: > Score how well every chart type fits a dataset. Deterministic — a rule-based scorer with no language model, so it returns a single result and uses no tokens. Only config.data is scored. The response is a Server-Sent Events (SSE) stream. Evaluation emits no progress events — the result arrives in a single complete event. operationId: evaluateDataset requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EvaluateRequest' example: 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 responses: '200': description: SSE stream with a single completion event content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/EvaluateCompleteEvent' - $ref: '#/components/schemas/ErrorEvent' '400': description: Bad Request - Invalid request body '401': description: Unauthorized - Invalid or missing API key components: schemas: EvaluateRequest: type: object description: >- Deterministic evaluation reads only config.data and the optional chartFamily — there is no userPrompt. properties: config: $ref: '#/components/schemas/GraphConfig' chartFamily: type: string enum: - comparison - relationship - distribution - composition description: >- Optional Abela chart-family hint. When set, chart types in that family get a fit bonus. metadata: $ref: '#/components/schemas/Metadata' required: - config EvaluateCompleteEvent: title: Evaluation complete event description: SSE event name is "complete". Evaluation emits no progress events. type: object properties: ranking: type: array items: $ref: '#/components/schemas/ChartFitEntry' description: Every supported chart type, scored and ranked by fit (best first). required: - ranking ErrorEvent: title: Error event description: SSE event name is "error" type: object properties: message: type: string GraphConfig: type: object description: >- The graph configuration object used to render charts. See [Graph Config Schema](/sdk/reference/graph-config) for the complete reference. properties: type: type: string enum: - line - areaStacked - bar - groupedBar - stackedBar - 100StackedBar - column - groupedColumn - stackedColumn - 100StackedColumn - combo - pie - donut - funnel - heatmap - scatter - bubble - waterfall - table - mekko description: The chart type data: type: object properties: columns: type: array items: type: object properties: key: type: string label: type: string rows: type: array items: type: object additionalProperties: true required: - type - data Metadata: type: object description: Optional tracking information for requests properties: callId: type: string description: >- Required when metadata is provided. Unique identifier for tracking and debugging. locale: type: string enum: - EN_GB - EN_US - AR - PT_PT description: Locale for responses effort: type: string enum: - low - medium - high description: >- Preferred invocation tier; forwarded on the invocation (including nested agents). When omitted, it can be inferred from `storytellingEffort` or defaults to `medium`. storytellingEffort: type: string enum: - none - low - medium - high description: >- Deprecated. Prefer `effort`. When set without `effort`, the server derives `effort` for propagation. For chart generation, an explicit value still controls narrative richness when both `effort` and `storytellingEffort` are present (`storytellingEffort` wins for the chart). required: - callId ChartFitEntry: type: object description: A single chart type, scored against the dataset. properties: rank: type: integer description: >- 1-based rank in the response array. Stable as scoring rules evolve — prefer it over score. type: type: string enum: - line - areaStacked - bar - groupedBar - stackedBar - 100StackedBar - column - groupedColumn - stackedColumn - 100StackedColumn - combo - pie - donut - funnel - heatmap - scatter - bubble - waterfall - table - mekko description: The chart type being scored. score: type: number description: >- Raw fit score. Drifts as rules change; use rank and verdict for stable checks. verdict: type: string enum: - ok - disqualified description: ok if the chart type is usable, disqualified if a rule rules it out. factors: type: array items: $ref: '#/components/schemas/ChartFitFactor' description: The individual reasons that contributed to the score. required: - rank - type - score - verdict - factors ChartFitFactor: type: object description: A single reason that contributed to a chart type's score. properties: kind: type: string enum: - deal-breaker - pro - con - family - specificity - continuity label: type: string description: Short label for the factor. weight: type: number description: How much the factor moved the score. reason: type: string description: Why the factor applies to this dataset. required: - kind - label - weight - reason securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Graphy API key (starts with graphy_). Create one in the Graphy console at https://agents.graphy.dev/console/ ````