---
title: Judgeval
seo:
  title: Judgeval — TypeScript SDK
  description: >-
    The main entry point for interacting with the Judgment platform. (TypeScript
    SDK)
description: 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.

```typescript
import { Judgeval } from "judgeval";

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

> **Throws**
>
> Error if any required credential is missing.

<Badge>
  Static Method
</Badge>

## create()

Create a new Judgeval client instance.

Resolves the `projectName` to a `projectId` via the Judgment API.

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

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

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `config` | `JudgevalConfig` | - | Configuration options. Credentials default to environment variables. |

### 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.

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

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

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `options?` | `{ signal?: AbortSignal; } \| undefined` | - | Pass signal to cancel the request with an AbortSignal. |

### 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.

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

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

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `sql` | `string` | - | One SELECT against the virtual schema, at most 50,000 characters. |
| `options?` | `{ signal?: AbortSignal; } \| undefined` | - | Pass signal to cancel the request with an AbortSignal. |

### 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()`](#sql) for new integrations, with SQL
predicates to narrow results. Existing JQL calls remain supported.

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

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `query` | `JqlQueryInput` | - | |
| `options?` | `JqlRequestOptions \| undefined` | - | |

### Returns

`Promise<JqlQueryResponse>`

***

## present()

Runs a legacy JQL chart or table query.

**Deprecated.** Use [`sql()`](#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.

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

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `query` | `PresentationQuery` | - | |
| `options?` | `JqlRequestOptions \| undefined` | - | |

### Returns

`Promise<JqlPresentationResponse>`

***

## discover()

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

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

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

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `kind` | `"judges" \| "behaviors" \| "span_names" \| "models" \| "fields" \| "rules" \| "judge_prompts" \| "judge_config" \| "citations"` | - | |
| `options?` | `(DiscoveryOptions & JqlRequestOptions) \| undefined` | - | |

### Returns

`Promise<JqlQueryResponse>`