Judgeval

The main entry point for interacting with the Judgment platform.

Judgeval connects to your Judgment project and gives you access to SQL queries, evaluations, datasets, and monitoring.

import { Judgeval } from "judgeval";

const client = await Judgeval.create({ projectName: "my-project" });

create()

Create a new Judgeval client instance.

Resolves the projectName to a projectId via the Judgment API.

const client = await Judgeval.create({
  projectName: "my-project",
  apiKey: "<your-api-key>",
  organizationId: "<your-organization-id>",
});

async function create(config: JudgevalConfig): Promise<Judgeval>

Parameters

Returns

Promise<Judgeval> - A new Judgeval instance.

discoverSchema()

Returns the server’s SQL reference as Markdown, matching MCP discover_schema: tables, columns, descriptions, examples, and limits. Requires organization viewer access, but no resolved project or query opt-in.

console.log(await client.discoverSchema());

async function discoverSchema(options?: { signal?: AbortSignal; } | undefined): Promise<string>

Parameters

Returns

Promise<string> - The virtual schema reference as a Markdown string; no project data.

sql()

Runs one read-only SQL SELECT for this organization and project.

The server derives scope from the client’s credentials and resolved project. Call discoverSchema() for supported tables and columns. Requires viewer access and public SDK/API queries enabled for the organization.

Results are capped at 1,000 rows and 5 MiB; exceeding either cap returns an error. Use SQL predicates and LIMIT to narrow results. Integers outside JavaScript’s safe range arrive as exact decimal strings.

const result = await client.sql("SELECT count() AS run_count FROM telemetry.traces");
console.log(result.rows);

async function sql(sql: string, options?: { signal?: AbortSignal; } | undefined): Promise<SqlResponse>

Parameters

Returns

Promise<SqlResponse> - An object with catalog_version, columns (name, type, nullable), rows (objects keyed by column name), row_count, and elapsed_ms.

query()

Runs a legacy JQL query.

Deprecated. Use sql() for new integrations, with SQL predicates to narrow results. Existing JQL calls remain supported.

async function query(query: JqlQueryInput, options?: JqlRequestOptions | undefined): Promise<JqlQueryResponse>

Parameters

Returns

Promise<JqlQueryResponse>

present()

Runs a legacy JQL chart or table query.

Deprecated. Use sql() for new queries and render its rows as charts or tables in your application. SQL does not return a JQL presentation frame. Existing presentation calls and their frame responses remain supported.

async function present(query: PresentationQuery, options?: JqlRequestOptions | undefined): Promise<JqlPresentationResponse>

Parameters

Returns

Promise<JqlPresentationResponse>

discover()

Discovers project-scoped judges, fields, models, and related values.

Deprecated. Use discoverSchema() to inspect the SQL tables and columns, then sql() to query project values. Schema discovery returns documentation, not project data. Existing JQL discovery calls remain supported; SQL returns a different row schema.

async function discover(kind: "judges" | "behaviors" | "span_names" | "models" | "fields" | "rules" | "judge_prompts" | "judge_config" | "citations", options?: (DiscoveryOptions & JqlRequestOptions) | undefined): Promise<JqlQueryResponse>

Parameters

Returns

Promise<JqlQueryResponse>