> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get the benchmark leaderboard > Returns one ranked page of a suite version’s published targets, each with the metric cells it is judged on. Ranking happens in the database, so paging through the board is consistent. Every default the server applies (suite version, condition, sort metric, sort direction) is echoed on the response, so a page can be cited without guessing how it was ordered. ## OpenAPI ````yaml /api-reference/openapi.documented.json get /v1/benchmark/leaderboard openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Config - name: CLI Auth - name: Call Analysis - name: Benchmark - name: Health paths: /v1/benchmark/leaderboard: get: tags: - Benchmark summary: Get the benchmark leaderboard description: >- Returns one ranked page of a suite version’s published targets, each with the metric cells it is judged on. Ranking happens in the database, so paging through the board is consistent. Every default the server applies (suite version, condition, sort metric, sort direction) is echoed on the response, so a page can be cited without guessing how it was ordered. operationId: getV1BenchmarkLeaderboard parameters: - in: query name: suite schema: type: string minLength: 1 required: true - in: query name: suiteVersion schema: type: string minLength: 1 required: false - in: query name: conditionKey schema: type: string required: false - in: query name: sortBy schema: type: string minLength: 1 required: false - in: query name: order schema: type: string enum: - asc - desc required: false - in: query name: metrics schema: type: string description: >- Comma-separated metric keys to project per row. Defaults to the headline set. required: false - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 20 description: 'Maximum number of records to return (default: 20, max: 100)' required: false - in: query name: offset schema: type: integer minimum: 0 default: 0 description: Pagination offset required: false responses: '200': description: One ranked page of the leaderboard content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/BenchmarkLeaderboardRow' suite: type: string suiteVersion: type: string description: The version actually read, after defaulting. conditionKey: type: string sortedBy: $ref: '#/components/schemas/BenchmarkSortDescriptor' pagination: $ref: '#/components/schemas/BenchmarkPagination' required: - data - suite - suiteVersion - conditionKey - sortedBy - pagination '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.benchmark.getLeaderboard({ suite: 'x' }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.benchmark.get_leaderboard( suite="x", ) print(response.data) components: schemas: BenchmarkLeaderboardRow: type: object properties: target: $ref: '#/components/schemas/BenchmarkTarget' metrics: type: array items: $ref: '#/components/schemas/BenchmarkResult' description: >- The projected cells for this row, measured under the requested condition. required: - target - metrics BenchmarkSortDescriptor: type: object properties: metricKey: type: string order: type: string enum: - asc - desc required: - metricKey - order description: The ranking this page was produced under BenchmarkPagination: type: object properties: limit: type: integer offset: type: integer total: type: integer description: Total matching records, ignoring this page. hasMore: type: boolean required: - limit - offset - total - hasMore ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message BenchmarkTarget: type: object properties: targetKey: type: string description: >- Stable identity of the model/stack across sweeps. Cite this, and pass it to the target endpoints. targetName: type: string description: Human-readable name of the model/stack. suite: type: string suiteVersion: type: string publicationId: type: string format: uuid description: >- Id of this one sweep. Changes every time the target is re-published, so it is a render key, not an identity. iterations: type: integer description: Calls the sweep requested per condition. sampleCallCount: type: integer description: Executed calls that contributed at least one score to these numbers. publishedAt: type: string description: When this sweep was published (ISO-8601), i.e. data freshness. supersededAt: type: - string - 'null' description: >- When a later sweep replaced this one. Null means it is the current generation. isCurrent: type: boolean description: Whether these are the numbers Roark publishes for this target today. required: - targetKey - targetName - suite - suiteVersion - publicationId - iterations - sampleCallCount - publishedAt - supersededAt - isCurrent description: A model or stack with a published result on a benchmark suite BenchmarkResult: type: object properties: conditionKey: type: string description: >- The flow variant these numbers were measured under. The empty string is the overall rollup across all conditions. conditionLabel: type: string metricKey: type: string description: Stable metric id, e.g. `response_time`. metricName: type: string metricKind: type: string enum: - NUMERIC - BOOLEAN description: >- Which statistics are populated on a result. NUMERIC fills p50/p95/mean/ci; BOOLEAN fills passRate and its interval. unitSymbol: type: - string - 'null' description: Display unit for numeric metrics, e.g. `ms`. 'n': type: integer description: Scored samples behind this aggregate. p50: type: - number - 'null' p95: type: - number - 'null' mean: type: - number - 'null' ciLow: type: - number - 'null' description: Low bound of the 95% CI of the mean (NUMERIC metrics). ciHigh: type: - number - 'null' passRate: type: - number - 'null' description: Fraction passed, 0..1 (BOOLEAN metrics). passRateCiLow: type: - number - 'null' description: Low bound of the 95% Wilson interval on the pass rate. passRateCiHigh: type: - number - 'null' required: - conditionKey - conditionLabel - metricKey - metricName - metricKind - unitSymbol - 'n' - p50 - p95 - mean - ciLow - ciHigh - passRate - passRateCiLow - passRateCiHigh description: 'One aggregate cell: a metric measured for one target under one condition' securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````