# obss data - Obss

CLI
obss 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 Obss returns bounded rows.
For ready-made summaries, start with
obss results analyze
. Use
data query
for what it doesn’t answer, or when its
page.completeData
points here.
obss data describe
List the datasets you can query, with their fields, the filters and aggregates each field takes, default order, and limits.
obss
data
describe
[flags]
Plugin (MCP) tool:
inspect_data_model
Takes only the
global flags
.
Examples
Read the model before you write a query:
obss
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.
obss data query
Run a JSON query over one dataset.
obss
data
query
--query
<
jso
n
>
[flags]
Plugin (MCP) tool:
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. Also takes the
global flags
.
Examples
Count trials by outcome:
obss
data
query
--query
'{"dataset":"trials","select":["outcome"],"groupBy":["outcome"],"aggregates":[{"function":"count","as":"trials"}]}'
--output
json
Compare passed trials by treatment in one experiment:
obss
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:
obss
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:
cat
cost-by-agent.json
|
obss
data
query
--query-file
-
--output
json
{
"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 Obss 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
.
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
;
obss 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
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 Obss 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
.
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
obss 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
obss runs trajectory
.
Next steps
obss runs and results
Ranked analysis, run profiles, and traces.
Evals
What Evals read, and their modes and models.
Insights
What Insights read, and their models.
Compare agents and models
Read the answer across agents, models, and treatments.
tags
agents and models
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform