Two modes

• Internal data analysis — you are querying Phoenix yourself to answer a question. Apply the schema facts, efficiency rules, and patterns below directly.
• Helping the user integrate — the user wants GraphQL queries for their own code or tools. Use the same schema facts and patterns, plus the "External API usage" section for endpoint, auth, and client examples. Queries you hand to the user should use variables and include pagination handling.

Entrypoints

Top-level Query entrypoints get you to a starting entity; per-entity schema details live in the reference files listed under "Schema map" below.

• node(id: ID!) — global lookup for any entity by its Relay global id; resolve with an inline fragment, e.g. node(id: $id) { ... on Dataset { name } }. This is the primary way to fetch datasets, prompts, experiments, sessions, and annotations, which have no by-name/by-id helpers.
• projects(...), datasets(...), prompts(...), evaluators(...) → Relay connections, each with filter/sort inputs to find an entity when you only have a name.
• By-X helpers (the only ones that exist): getProjectByName(name: String!), getProjectSessionById(sessionId: String!), getDatasetExampleByExternalId(datasetId: GlobalID!, externalId: String!), getSpanByOtelId(spanId: String!), getTraceByOtelId(traceId: String!). There is no getDatasetByName, getPromptByName, or getExperimentById — use node(id:) or a connection filter instead.
• viewer → the authenticated User; projectCount, datasetCount, promptCount — cheap counts.
• compareExperiments(baseExperimentId: GlobalID!, compareExperimentIds: [GlobalID!]!, first, after, filterCondition) → experiment comparison.

Schema map

Per-entity field references and examples are split into reference files. Load only the one(s) you need with load_skill_reference, after loading this skill:

• Projects, spans, and traces: Project aggregates and spans; Span and Trace fields. The starting point for most trace analysis.
• Sessions: ProjectSession multi-turn session metrics, token/cost, and session traces.
• Datasets: Dataset and DatasetExample examples, versions, splits, and labels.
• Experiments: Experiment and ExperimentRun runs, aggregate metrics, and comparison.
• Prompts: Prompt and PromptVersion versions, templates, and tags.
• Annotations: Span, trace, session, and experiment-run annotation fields; how to read them; and the mutations that write notes, labels, and annotation configs.
• Filter expressions: The span, trace, and session filter languages (filterCondition, traceFilterCondition, sessionFilterCondition), including vocabulary, operators, root-span scoping, and compiled examples. Load it before writing any condition beyond the one-liners below.

Conventions

These apply to every entity:

• Pagination is Relay-style: first/after args; responses have edges { node { ... } } and pageInfo { hasNextPage endCursor }. Cursors are opaque strings. Some connections (e.g. Project.spans, Experiment.runs, ProjectSession.traces) are forward-only.
• IDs: the id field on any node is a Relay global ID (base64 of TypeName:rowId) — use it with node(id:). OpenTelemetry hex IDs come from Span.spanId and Trace.traceId — use those for OTel lookups. Note a Span has no traceId field; read it via the nested trace { traceId }. Never mix global IDs with OTel IDs.
• TimeRange input: { start: DateTime, end: DateTime } — ISO 8601 strings; end is exclusive; both optional.
• SpanSort input: { col: SpanColumn, dir: SortDir }, e.g. { col: startTime, dir: desc }. Useful SpanColumn values: startTime, latencyMs, tokenCountTotal, cumulativeTokenCountTotal, tokenCostTotal.
• Filter conditions (filterCondition, traceFilterCondition, sessionFilterCondition) are Python boolean expressions, one language each for spans, traces, and sessions, e.g. span_kind == 'LLM', status_code == 'ERROR', 'timeout' in output.value, annotations['Hallucination'].label == 'hallucinated'. There is no traces connection: list traces with the clause parent_span is None (root spans, orphans included), or parent_id is None for spans with no parent id. Unknown span filter names compile as attribute paths and match nothing, so read references/filter-expressions.md before writing a condition.

Efficiency rules

• Do not run full schema introspection. Read the relevant Schema map resource instead; it covers the fields and arguments for that entity. Only when a resource does not cover a field you need, introspect a single type: { __type(name: "Project") { fields { name args { name type { name kind } } } } }.
• Batch independent lookups with aliases in one query instead of multiple round trips, e.g. p50: latencyMsQuantile(probability: 0.5) p99: latencyMsQuantile(probability: 0.99).
• Select only the fields you need; keep page sizes small (10–50) and paginate only when necessary.
• Pass values via query variables, never string interpolation. A document may be at most 2 KiB of UTF-8, and variable values do not count toward it.
• Span input/output payloads can be huge — request input { truncatedValue } (first 100 chars) when surveying; fetch input { value } (full payload) only for spans you intend to read closely.

Patterns

Two canonical shapes to orient you; entity-specific examples live in each resource.

Reach an entity and read fields via node(id:) + an inline fragment:

query GetEntity($id: ID!) {
  node(id: $id) {
    ... on Dataset { name exampleCount }
  }
}

Batch independent project aggregates with aliases in one round trip:

query Overview($name: String!, $timeRange: TimeRange) {
  getProjectByName(name: $name) {
    traceCount(timeRange: $timeRange)
    p50: latencyMsQuantile(probability: 0.5, timeRange: $timeRange)
    p99: latencyMsQuantile(probability: 0.99, timeRange: $timeRange)
    errorCount: recordCount(timeRange: $timeRange, filterCondition: "status_code == 'ERROR'")
  }
}

Execution surfaces (internal mode)

• phoenix-gql (bash): run phoenix-gql --help for flags and current permissions. Use --data-only when piping to jq, --output <file> for large results, --vars '<json>' for variables. Mutations are allowed only when runtime permissions say so; the tool reports its permissions on every invocation.

External API usage (user-facing mode)

Facts users need to call the API themselves:

• Endpoint: POST <phoenix-endpoint>/graphql with a JSON body { "query": "...", "variables": { ... } }, where <phoenix-endpoint> is the Phoenix base URL from PHOENIX_ENDPOINT. A GraphiQL IDE is served on GET at the same path.
• Auth: send a Phoenix API key as a bearer token: Authorization: Bearer <API_KEY>. API keys are created in Phoenix settings.
• The GraphQL schema is primarily designed for the Phoenix UI and may change between versions; for stable programmatic access, recommend the REST API (/v1/...) and the arize-phoenix-client Python / @arizeai/phoenix-client TypeScript packages where they cover the need, and GraphQL for everything else.

curl:

curl -s "$PHOENIX_ENDPOINT/graphql" \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "query($n: String!) { getProjectByName(name: $n) { traceCount } }", "variables": {"n": "default"}}'

Python:

import httpx

resp = httpx.post(
    f"{endpoint}/graphql",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"query": query, "variables": variables},
)
resp.raise_for_status()
data = resp.json()["data"]

When handing users a query, include: the full operation with variable definitions, an example variables payload, and a note on paginating via pageInfo { hasNextPage endCursor } → pass endCursor as after.