> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# oqoqo data

> List the datasets and fields you can query, then filter, group, and count experiments, runs, trials, Evals, Insights, and frictions from the CLI.

Ask your own questions of your results, such as pass counts by treatment, cost by agent, or Evals attempts by model. You send a JSON query (never SQL) over a fixed set of datasets, and Oqoqo returns bounded rows.

For ready-made summaries, start with [`oqoqo results analyze`](https://docs.oqoqo.ai/cli/runs#oqoqo-results-analyze). Use `data query` for what it doesn't answer, or when its `page.completeData` points here.

## oqoqo data describe

List the datasets you can query, with their fields, the filters and aggregates each field takes, default order, and limits.

```bash theme={null}
oqoqo data describe [flags]
```

**Plugin (MCP) tool:** [`inspect_data_model`](https://docs.oqoqo.ai/mcp-server/tags-and-data#inspect_data_model)

Takes only the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Read the model before you write a query:

```bash theme={null}
oqoqo data describe --output json
```

**Result fields**

| Field | Meaning |
| - | - |
| `datasets` | Each dataset's `name`, `title`, `description`, `grain` (what one row is), `fields`, `identityFields` (the fields that identify a row), `defaultSelect`, and `defaultOrder` |
| `datasets[].fields` | Each field's `name`, `type` (`string`, `number`, `boolean`, or `timestamp`), `nullable`, `description`, `filterOperators`, and `aggregates` |
| `limits` | The query limits |

**Notes**

The model is the same in every project.

## oqoqo data query

Run a JSON query over one dataset.

```bash theme={null}
oqoqo data query --query <json> [flags]
```

**Plugin (MCP) tool:** [`query_data`](https://docs.oqoqo.ai/mcp-server/tags-and-data#query_data)

**Flags**

| Flag | Type | Default | Description |
| - | - | - | - |
| `--query` | string | | The query as inline JSON. |
| `--query-file` | file path | | A file that holds the query JSON, or `-` to read it from stdin. |

Pass one of the two, structured as described under [Query JSON](#query-json) for the datasets and fields under [Datasets](#datasets). Also takes the [global flags](https://docs.oqoqo.ai/cli/overview.md#global-flags).

**Examples**

Count trials by outcome:

```bash theme={null}
oqoqo data query --query '{"dataset":"trials","select":["outcome"],"groupBy":["outcome"],"aggregates":[{"function":"count","as":"trials"}]}' --output json
```

Compare passed trials by treatment in one experiment:

```bash theme={null}
oqoqo data query --query '{"dataset":"runs","filters":[{"field":"experimentId","operator":"eq","value":"exp_8f2c41d0"}],"select":["treatmentName"],"groupBy":["treatmentName"],"aggregates":[{"function":"sum","field":"passedTrialCount","as":"passed"},{"function":"sum","field":"completedTrialCount","as":"completed"}]}'
```

Count Evals attempts by mode and Evals model:

```bash theme={null}
oqoqo data query --query '{"dataset":"evals","select":["mode","evalsModelName"],"groupBy":["mode","evalsModelName"],"aggregates":[{"function":"count","as":"attempts"}]}'
```

Average cost per trial by agent, split by cost source:

```bash theme={null}
cat cost-by-agent.json | oqoqo data query --query-file - --output json
```

```json theme={null}
{
  "dataset": "trials",
  "select": ["agentName", "costSource"],
  "groupBy": ["agentName", "costSource"],
  "aggregates": [{ "function": "avg", "field": "costUsd", "as": "avgCostUsd" }],
  "orderBy": [{ "field": "agentName", "direction": "asc" }]
}
```

**Result fields**

| Field | Meaning |
| - | - |
| `columns` | Each column's `name`, `type`, and `aggregate` |
| `rows` | The rows of this page |
| `query` | The query as Oqoqo ran it |
| `page` | `returned`, `hasMore`, `nextCursor`, `truncated`, and `reasons` |
| `limits` | The query limits |

**Notes**

While `hasMore` is true, send the query again with `nextCursor` as its `cursor`. When `truncated` is true, `reasons` says why the page holds less than everything that matched:

| Reason | Meaning |
| - | - |
| `row_limit` | The page reached the query's `limit`. |
| `cursor_window` | Paging passed 10,000 rows. Narrow the filters. |
| `byte_limit` | The response reached 20 KiB. Select fewer fields. |
| `cell_limit` | A value was longer than 4,096 bytes and was cut. |
| `secure_value_redacted` | A value looked like a secret and was removed. |

A query that doesn't match the model fails with a usage error that names each problem, such as an unknown field or an operator the field doesn't take.

## Query JSON

| Field | Type | Default | Description |
| - | - | - | - |
| `dataset` | string | | Required. A dataset name from [Datasets](#datasets). |
| `select` | list of field names | The dataset's `defaultSelect` | 1 to 12 fields to return. With `groupBy`, select the group fields. |
| `filters` | list | `[]` | Up to 20 filters, and a row must match all of them. Each is `{ "field", "operator", "value" }`. |
| `groupBy` | list of field names | `[]` | Up to 4 fields to group by. |
| `aggregates` | list | `[]` | Up to 8. Each is `{ "function", "field", "as" }`; `as` names the column, and `count` needs no `field`. |
| `orderBy` | list | The dataset's `defaultOrder` | Up to 4 `{ "field", "direction" }`, with `asc` (default) or `desc`. |
| `limit` | integer | `100` | Rows per page, at most 200. |
| `cursor` | string | | The `nextCursor` of the previous page. |

| Filter `operator` | `value` |
| - | - |
| `eq`, `neq`, `lt`, `lte`, `gt`, `gte` | One value. |
| `in`, `not_in` | A list of up to 100 values. |
| `contains`, `starts_with` | Text, for string fields. |
| `is_null`, `is_not_null` | None. |

Aggregate functions are `count`, `count_distinct`, `sum`, `avg`, `min`, and `max`; `oqoqo data describe` lists what each field takes. Timestamps are ISO 8601 strings. A query runs for at most 3 seconds and returns at most 200 rows and 20 KiB.

## Datasets

| Dataset | One row is | Fields |
| - | - | - |
| `resources` | One current task, file, machine, tool, treatment, or agent | `kind`, `id`, `key`, `name`, `description`, `status`, `version`, `isOfficial`, `isReadOnly`, `createdAt`, `updatedAt` |
| `experiments` | One experiment | `id`, `label`, `description`, `category`, `status`, `taskCount`, `runCount`, `createdAt`, `startedAt`, `completedAt`, `updatedAt` |
| `runs` | One task × treatment × agent combination, with trial counts. Each trial is one billed run. | `id`, `experimentId`, `taskId`, `taskKey`, `taskName`, `treatmentKey`, `treatmentName`, `agentKey`, `agentName`, `agentKind`, `modelId`, `modelName`, `effortLevel`, `providerDisplayName`, `status`, `trialCount`, `completedTrialCount`, `passedTrialCount`, `failedTrialCount`, `createdAt`, `updatedAt` |
| `trials` | One trial of a run | `id`, `runId`, `experimentId`, `taskId`, `taskKey`, `taskName`, `treatmentKey`, `treatmentName`, `agentName`, `agentKind`, `modelId`, `modelName`, `effortLevel`, `providerDisplayName`, `status`, `outcome`, `trialOrdinal`, `durationMs`, `agentExecutionMs`, `inputTokens`, `outputTokens`, `costUsd`, `costSource`, `toolCallCount`, `frictionCount`, `startedAt`, `completedAt` |
| `evals` | One Evals attempt for one experiment | `id`, `experimentId`, `status`, `sequence`, `source`, `totalRunCount`, `completedRunCount`, `skippedRunCount`, `failedRunCount`, `passCount`, `failCount`, `createdAt`, `startedAt`, `completedAt`, `updatedAt`, `evalsModelId`, `evalsModelName`, `mode` |
| `insights` | One Insights attempt for one experiment | `id`, `experimentId`, `status`, `sequence`, `source`, `totalRunCount`, `completedRunCount`, `skippedRunCount`, `failedRunCount`, `passCount`, `failCount`, `createdAt`, `startedAt`, `completedAt`, `updatedAt`, `insightsModelId`, `insightsModelName`, `experimentInsightsModelId`, `experimentInsightsModelName`, `mode` |
| `evalsResults` | One trial in one Evals attempt | `attemptId`, `experimentId`, `runId`, `trialId`, `taskId`, `status`, `outcome`, `createdAt`, `completedAt` |
| `insightsResults` | One trial in one Insights attempt | `attemptId`, `experimentId`, `runId`, `trialId`, `taskId`, `status`, `outcome`, `createdAt`, `completedAt` |
| `frictions` | One friction in one trial | `id`, `experimentId`, `runId`, `trialId`, `taskId`, `taskKey`, `treatmentName`, `agentName`, `family`, `name`, `headline`, `recovery`, `insightsModelId`, `insightsModelName`, `experimentInsightsModelId`, `experimentInsightsModelName`, `createdAt` |
| `trajectorySteps` | One step of a trial's trace | `experimentId`, `runId`, `trialId`, `ordinal`, `kind`, `isToolCall`, `originResolution`, `surfaceKind`, `surfaceName`, `toolOperation`, `toolName`, `durationMs`, `turn` |
| `runTurns` | One model turn of a trial | `experimentId`, `runId`, `trialId`, `ordinal`, `startedAt`, `inputTokens`, `cachedInputTokens`, `outputTokens`, `costUsd` |
| `surfaceUsage` | One skill, MCP server, CLI, SDK, or machine in one trial | `experimentId`, `runId`, `trialId`, `kind`, `key`, `name`, `isTreatment`, `use`, `callCount`, `firstStepOrdinal` |

### Fields to know

| Field | Description |
| - | - |
| `evals.mode`, `insights.mode` | `standard` or `agent`. Attempts from before [Agent mode](https://docs.oqoqo.ai/evaluation/agent-mode.md) are `standard`. |
| `evals.evalsModelId`, `evalsModelName` | The Evals model saved when the attempt was requested. `null` if the attempt didn't run or predates saved models. |
| `insights.insightsModelId`, `insightsModelName`, `experimentInsightsModelId`, `experimentInsightsModelName` | The Insights model and the Experiment insights model, saved the same way. |
| `frictions.insightsModelName` and the other model fields | The models of the Insights attempt that found the friction. `null` for a trial that failed before the agent answered. A trial an Oqoqo error stopped has no `frictions` row. |
| `passCount`, `failCount` | Passing and failing Evals results. Always `0` in `insights`. |
| `source` | Whether the attempt is the original or a retry |
| `trials.costUsd`, `costSource` | Cost in USD, and its source: `agent_reported` (the agent's own total), `estimated` (tokens × list prices), or `unknown`. Group by `costSource` before you average, so you don't blend sources. |
| `trials.durationMs`, `agentExecutionMs` | Total trial time including setup, and the agent's working time, in ms |
| `trials.trialOrdinal` | The repeat number, starting at `0`. |
| `runs.agentKind`, `trials.agentKind` | `built_in`, or `custom` for an agent your organization added. |
| `runs.modelName`, `trials.modelName` | The model's name at launch. Use it for labels: a custom agent's `modelId` is its own option value. |
| `frictions.family` | `product_gap`, `docs_gap`, `environment_gap`, `agent_harness_gap`, `agent_reasoning_gap`, or `task_quality_gap`. See [Frictions](https://docs.oqoqo.ai/evaluation/frictions.md). |
| `frictions.recovery` | Whether the trial recovered: `recovered`, `unrecovered`, or `unknown`. |
| `frictions.id` | The `frc_` ID, with one row per trial once Insights groups it. See [`oqoqo frictions get`](https://docs.oqoqo.ai/cli/frictions#oqoqo-frictions-get). |
| `trajectorySteps.originResolution` | Where a step came from: `surface`, `native`, `ambiguous`, `unresolved`, `unavailable`, or `not_applicable`. |
| `trajectorySteps.turn`, `runTurns.ordinal` | A step's `turn` is the `ordinal` of the model turn that produced it. Turn usage is never split across its tool calls. |
| `runTurns.inputTokens`, `cachedInputTokens` | The turn's full input, cached tokens included, and the cached part |
| `surfaceUsage.use` | `used`, `not_used`, `not_measured`, `inconclusive`, or `not_applicable`. `callCount` is `0` when unused, `null` while undecided. |
| `surfaceUsage.isTreatment` | `true` when the tool came from the treatment, not the agent or machine |

The `frictions` fields `category`, `phase`, `confidence`, `severity`, `classification`, and `owner` are always `null` and stay only so older queries run. No dataset holds message text or tool input and output; read those with [`oqoqo runs trajectory`](https://docs.oqoqo.ai/cli/runs#oqoqo-runs-trajectory).

## Related

> [card] [oqoqo runs and results](https://docs.oqoqo.ai/cli/runs.md)
>
> Ranked analysis, run profiles, and traces.

> [card] [Evals](https://docs.oqoqo.ai/evaluation/evals.md)
>
> What Evals read, and their modes and models.

> [card] [Insights](https://docs.oqoqo.ai/evaluation/insights.md)
>
> What Insights read, and their models.

> [card] [Compare agents and models](https://docs.oqoqo.ai/guides/compare-agents-and-models.md)
>
> Read the answer across agents, models, and treatments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.