Client methods

judgeval JQL source on GitHub

Public methods

client.query(query, *, limit=None, trace_ids=None, session_ids=None) -> JqlQueryResponse
client.present(query, *, limit=None, trace_ids=None, session_ids=None) -> JqlPresentationResponse
client.discover(kind, *, limit=None, trace_ids=None, session_ids=None, **options) -> JqlQueryResponse

Request options: trace and session scope

Use trace_ids or session_ids to narrow a query to one or more traces. The options are mutually exclusive:

from judgeval.jql import spans

result = client.query(spans().rows(), trace_ids=["trace-123"])

Trace and session IDs are outer request options, not part of the canonical JQL JSON IR. Trace IDs bind directly to a trace-scoped project. Judgment resolves session IDs within the authenticated organization and project first. Every compiled part of the query is narrowed to the resulting traces. Both options work with query, present, and discover.

Each list must contain 1–1,000 non-blank IDs, each at most 512 characters. If no session resolves to a trace, the request fails with BAD_SCOPE; it never widens to the whole project. Organization and project remain the tenant-isolation boundary.

Request option: limit

limit is an integer from 1 through 10,000, validated by the public API. When omitted, the SDK sends 10,000.

• The request-envelope limit replaces any limit inside the JQL object — it is not a min(). Because the public API always sends one, an inner .rows(... limit ...) of 100 is widened to 10,000 unless you also set the method-level limit.
• Set the method-level limit whenever you want a smaller result.
• The envelope limit is ignored for terminals that do not produce a limitable result, such as count and agg.
• client.discover forwards its limit only as the request cap. To set the IR-level discovery limit, build the discovery object directly and pass it to client.query.
• An out-of-range limit is rejected as a 400 with error Validation failed, not BAD_QUERY.

Transport

The SDK sends:

{
  "query": { "op": "query", "source": "traces", "select": { "op": "ids" } },
  "limit": 100,
  "trace_ids": ["trace-123"]
}

to the project-scoped query endpoint. present uses a separate /query/presentation endpoint; discover shares the query endpoint. The SDK supplies Authorization: Bearer <api key>, the X-Organization-Id header, and the resolved project ID as a path parameter. The public response never includes compiled SQL — it is stripped at the API boundary.

Use Responses and errors for the exact success and failure shapes.