# obss runs and results - Obss

CLI
obss runs and results
List runs, read a run’s profile, trajectory, transcript, and output, and analyze results from the terminal.
Page through a project’s runs, open one run’s recorded work, or analyze many runs at once. In the dashboard, the same results are on
Read results
and
Run details
.
A run is one agent attempt on one task with one treatment. Each trial is its own run, so a trial ID is also a
run_
ID.
Run scope flags
The run scope flags narrow a command to the runs that a set of records shaped.
obss runs list
,
obss frictions list
, and
obss frictions get
take all of them.
obss experiments list
takes all of them except
--experiment-id
, and lists the experiments of those runs.
obss results analyze
takes them too, but its
--experiment-id
,
--task-id
, and
--friction-id
are its own analysis flags.
Flag
Takes
Counts only the runs
--experiment-id
exp_
Of this experiment
--schedule-id
sch_
Of the experiments this schedule launched
--task-id
tsk_
Of this task, in every version
--task-version-id
tskver_
Of this task version
--treatment-id
trt_
Of this treatment (toolset)
--tool-id
skl_
,
mcp_
,
cli_
,
sdk_
Whose treatment gave the agent this skill, MCP server, CLI, or SDK, in any version
--tool-version-id
sklver_
,
mcpver_
,
cliver_
,
sdkver_
Whose treatment gave the agent this tool version
--file-id
fld_
Whose task had this file
--machine-id
env_
Whose task ran on this machine
--agent-id
An agent key, such as
claude-code
Of this agent, with any model. The key is a run’s
agentId
.
--agent-model-id
agm_
Of this agent and model, from
obss catalog list --kind agent
--friction-id
frc_
Where this friction occurred
Each flag takes one ID, and a run counts only when it matches every flag you pass.
An ID with the wrong prefix is a usage error. The message says where the right ID comes from.
An ID that the project doesn’t have fails with
scope_not_found
instead of returning an empty list. The error names each ID it couldn’t find.
The runs and frictions results return
scope
: each record they counted, with its
kind
,
id
, current
name
, and
dashboardUrl
.
obss runs list
Page every run of the current project, newest first, with stable IDs, outcomes, and errors.
obss
runs
list
[flags]
Plugin (MCP) tool:
list_runs
Flags
Flag
Type
Default
Description
--experiment-id
string
Only the runs of this
exp_
experiment.
--schedule-id
string
Only the runs of the experiments that this
sch_
schedule launched.
--task-id
string
Only the runs of this
tsk_
task, in every version.
--task-version-id
string
Only the runs of this
tskver_
task version.
--treatment-id
string
Only the runs of this
trt_
treatment (toolset).
--tool-id
string
Only the runs whose treatment gave the agent this skill, MCP server, CLI, or SDK (
skl_
,
mcp_
,
cli_
, or
sdk_
), in any version.
--tool-version-id
string
Only the runs whose treatment gave the agent this tool version (
sklver_
,
mcpver_
,
cliver_
, or
sdkver_
).
--file-id
string
Only the runs whose task had this
fld_
file.
--machine-id
string
Only the runs whose task ran on this
env_
machine.
--agent-id
string
Only the runs of this agent key, such as
claude-code
, with any model.
--agent-model-id
string
Only the runs of this
agm_
agent and model.
--friction-id
string
Only the runs where this
frc_
friction occurred.
--query
string
Words in the task name or key, the agent, the model, or the run ID.
--status
string
Comma-separated run statuses:
queued
,
running
,
completed
,
errored
, or
cancelled
. At most 20.
--outcome
string
Comma-separated outcomes, such as
pass
,
fail
,
evals_failed
,
infra_blocked
, or
inconclusive
. At most 20.
--task-key
string
Only the runs of the task with this key.
--treatment
string
Only the runs of the treatment with this key or label.
--agent
string
Only the runs of the agent with this key or name.
--model-id
string
Only the runs of this model ID.
--effort-level
string
Only the runs at this effort level.
--provider
string
Only the runs on the provider connection with this exact name, as
providerDisplayName
reports it.
--completed-after
string
Only the runs that completed at or after this ISO 8601 date-time.
--completed-before
string
Only the runs that completed before this ISO 8601 date-time.
--limit
integer
50
Results per page, up to 200 (default 50).
--cursor
string
The
nextCursor
from the previous page.
The first twelve flags are the
run scope flags
. Also takes the
global flags
.
Examples
List the failed runs of one experiment:
obss
runs
list
--experiment-id
exp_8f2c41d0
--outcome
fail
List every run where a friction occurred:
obss
runs
list
--friction-id
frc_7d20e6b4
--output
json
List every run whose treatment gave the agent one MCP server:
obss
runs
list
--tool-id
mcp_2e8b6f13
--output
json
Result fields
Each run has its
runId
and
trialId
, the task, the treatment, and the agent with its model and effort, plus these fields. The result also has
scope
,
hasMore
, and
nextCursor
.
Field
Meaning
criteriaSummary
The result in plain words.
treatmentUse
Whether the agent used the treatment, with each skill, MCP server, CLI, and SDK and its state.
null
when the run has no usable
run profile
.
error
A typed error with a
code
and a
message
, when the run errored.
blockedReason
On a blocked run, its
cause
and a one-line
message
.
setupFailure
Present when a setup command stopped the run before its agent started. The fields are in the next table.
providerDisplayName
The provider connection’s name. Runs that share agent, model, and effort can differ only by this field; filter them with
--provider
.
setupFailure
field
Meaning
owner
The machine, CLI, or SDK step that declared the command.
null
for a package install.
commandNumber
Which command failed, when the owner has several commands of that kind
manager
,
packageOwners
For a package install, the package manager and who declared the packages
command
The command that failed
exitCode
or
timeoutSeconds
How it failed
output
Its last output lines
Notes
Continue with
--cursor
while
hasMore
is true. To fix a setup failure, see
A run could not start because a setup command failed
.
obss runs profile
Show where one run’s tool calls, time, and tokens went, and which skills, MCP servers, CLIs, and SDKs from its treatment the agent used.
obss
runs
profile
<
run-i
d
>
[flags]
Plugin (MCP) tool:
get_run_profile
Arguments
Argument
Description
<run-id>
Required. The run’s
run_
ID.
Takes only the
global flags
.
Examples
obss
runs
profile
run_6b31e09f
--output
json
Notes
This is the
Run profile
rail on run details: treatment use, tool calls, what stood out, and time. Counts and times are exact or absent, because Obss never estimates a missing count or time.
A run that a setup command stopped has
setupFailure
, with the fields listed under
obss runs list
. The text output names the step and what to fix, prints the
obss resources inspect
command for the machine or tool that declared it, then shows the command and its output.
obss runs trajectory
Read one page of a run’s ordered steps, with token usage and measured tool durations.
obss
runs
trajectory
<
run-i
d
>
[flags]
Plugin (MCP) tool:
get_run_trajectory
Arguments
Argument
Description
<run-id>
Required. The run’s
run_
ID.
Flags
Flag
Type
Default
Description
--after-ordinal
integer
Start after this step. Send the
nextAfterOrdinal
of the previous page. The minimum is
-1
.
--projection
compact
,
full
compact
compact
gives each step a text preview of up to 512 bytes.
full
gives each step’s complete recorded fields.
--limit
integer
100
Results per page, up to 500 (default 100).
Also takes the
global flags
.
Examples
Read the first 500 steps, then the next page:
obss
runs
trajectory
run_6b31e09f
--limit
500
--output
json
obss
runs
trajectory
run_6b31e09f
--after-ordinal
499
--output
json
Result fields
Field
Meaning
Steps
In ordinal order, grouped by the model turn that produced them.
truncated
,
nextAfterOrdinal
While
truncated
is true, more steps remain. Send
nextAfterOrdinal
as
--after-ordinal
to read the next page.
coverage
firstOrdinal
,
lastOrdinal
,
totalSteps
, and
complete
.
Run header tokens and cost
The reported input, cached input, and output tokens, and the cost with its
costSource
. Unknown totals stay
null
.
stopReason
,
reportedModelId
,
reportedModelName
,
agentError
For a
custom agent
only: why it stopped, the model it reported, and why it failed before it answered. These fields are
null
for other agents.
setupFailure
Present when a setup command stopped the run, as in
obss runs list
.
Notes
For a summary of the whole run, use
obss runs profile
.
obss runs transcript
Read one byte-bounded page of a run’s original transcript, unchanged.
obss
runs
transcript
<
run-i
d
>
[flags]
Plugin (MCP) tool:
get_run_transcript
Arguments
Argument
Description
<run-id>
Required. The run’s
run_
ID.
Flags
Flag
Type
Default
Description
--trial-id
string
Read this trial’s transcript, by its
run_
ID.
--offset
integer
0
The byte to start from. Send the
nextOffset
of the previous page.
--limit-bytes
integer
12288
Content bytes in one page, up to 12,288 (default 12,288).
Also takes the
global flags
.
Examples
Read the first page, then the next:
obss
runs
transcript
run_6b31e09f
--output
json
obss
runs
transcript
run_6b31e09f
--offset
12288
--output
json
Result fields
Field
Meaning
fileName
The transcript’s file name.
byteSize
,
sha256
The size and SHA-256 of the whole file.
nextOffset
,
eof
Continue with
--offset
set to
nextOffset
until
eof
is true.
Notes
Use
--output json
to receive the exact bytes. It’s the same file that
⋯ → Download trajectory
saves on
run details
.
obss runs output
Read what a run left behind: the file manifest, a diff of one file or the whole run, one file, the agent’s final message, or the full archive.
obss
runs
output
<
run-i
d
>
[flags]
Plugin (MCP) tool:
get_run_output
Arguments
Argument
Description
<run-id>
Required. The run’s
run_
ID.
Flags
Flag
Type
Default
Description
--part
final_message
,
diff
,
manifest
,
archive
,
file
manifest
What to read.
manifest
lists the files.
diff
is the whole-run diff, or one file’s diff with
--path
.
file
is one file.
final_message
is the agent’s last message.
archive
is every retained file.
--path
string
The file to read with
--part file
, or to diff with
--part diff
. At most 4,096 characters.
--trial-id
string
Read this trial’s output, by its
run_
ID.
--offset
integer
0
The byte to start from. Send the
nextOffset
of the previous page.
--limit-bytes
integer
12288
Content bytes in one page, up to 12,288 (default 12,288).
Also takes the
global flags
.
Examples
List the files a run changed, then read one file’s diff:
obss
runs
output
run_6b31e09f
obss
runs
output
run_6b31e09f
--part
diff
--path
src/checkout/cart.ts
Result fields
Field
Meaning
nextOffset
,
eof
Continue with
--offset
set to
nextOffset
until
eof
is true.
sourceTruncated
When true, the
final_message
part is a preview. Read the complete original with
obss runs transcript
.
Notes
Use
--output json
to receive the exact bytes. The dashboard shows the same files on the
Output
tab of
run details
.
obss results analyze
Run one structured analysis over the runs in a scope: summarize, compare treatments, find failures and frictions, or read one run’s evidence.
obss
results
analyze
<
mod
e
>
[flags]
Plugin (MCP) tool:
analyze_results
Arguments
Argument
Description
<mode>
Required. The analysis to run. See
Modes
.
Flags
Flag
Type
Default
Description
--query
string
Words to search for, in the search modes.
--experiment-id
string
Only the runs of this
exp_
experiment.
--run-id
string
One run, by its
run_
ID.
--trial-id
string
One trial, by its
run_
ID.
--runs
string
Up to 3 comma-separated
run_
IDs to analyze together, as
Compare
does. A
run~trial
item names one trial of a run.
--task-id
string
Only the runs of this
tsk_
task.
--task-key
string
Only the runs of the task with this key.
--skill-id
string
Only the runs that involve this
skl_
skill.
--skill-key
string
Only the runs that involve the skill with this key.
--friction-id
string
Only the runs where this
frc_
friction occurred.
--schedule-id
string
Only the runs of the experiments that this
sch_
schedule launched.
--task-version-id
string
Only the runs of this
tskver_
task version.
--treatment-id
string
Only the runs of this
trt_
treatment (toolset).
--tool-id
string
Only the runs whose treatment gave the agent this skill, MCP server, CLI, or SDK (
skl_
,
mcp_
,
cli_
, or
sdk_
), in any version.
--tool-version-id
string
Only the runs whose treatment gave the agent this tool version (
sklver_
,
mcpver_
,
cliver_
, or
sdkver_
).
--file-id
string
Only the runs whose task had this
fld_
file.
--machine-id
string
Only the runs whose task ran on this
env_
machine.
--agent-id
string
Only the runs of this agent key, such as
claude-code
, with any model.
--agent-model-id
string
Only the runs of this
agm_
agent and model.
--treatment
string
Only the runs of the treatment with this key or label.
--outcome
pass
,
fail
,
evals_failed
,
infra_blocked
,
inconclusive
Only the runs with this outcome.
inconclusive
leaves out the runs that Evals can still judge.
--agent
string
Only the runs of the agent with this name or key.
--model-id
string
Only the runs of this model ID.
--effort-level
string
Only the runs at this effort level.
--provider
string
Only the runs on the provider connection with this exact name.
--completed-after
string
Only the runs that completed at or after this ISO 8601 date-time.
--completed-before
string
Only the runs that completed before this ISO 8601 date-time.
--limit
integer
The most ranked items to return, up to 100. Ranked analysis is never paged.
--schedule-id
through
--agent-model-id
are
run scope flags
. Also takes the
global flags
.
Modes
Mode
What it returns
summarize_scope
Runs, passes, and failures per treatment and per agent, with
pendingRuns
,
inconclusiveRuns
, and
insightsCoverage
compare_treatments
Each treatment against the Baseline: pass and fail counts, use rate, mean tokens, working time, tool calls, and mean cost per cost source, with the difference from the Baseline. It also counts
pendingRuns
and
inconclusiveRuns
.
find_failure_patterns
Recurring failures in the scope
search_experiment_evidence
Recorded evidence that matches
--query
search_frictions
Frictions that match
--query
, with
insightsCoverage
get_run_evidence
One run’s evidence, with its
status
,
evalsPending
, and
insightsPending
. Needs
--run-id
, or a trial’s
run_
ID in
--trial-id
.
rank_tasks_by_friction
Tasks ranked by their frictions
analyze_reasoning_gaps
Where agents reasoned badly
find_similar_failures
Failures like the ones in the scope
analyze_skill_usage
How agents used the skills they were given
compare_treatments
compares mean costs only within one cost source, so it never mixes costs that the agent reported with costs that Obss estimated.
Examples
Summarize one experiment:
obss
results
analyze
summarize_scope
--experiment-id
exp_8f2c41d0
--output
json
Print each treatment’s pass rate:
obss
results
analyze
compare_treatments
--experiment-id
exp_8f2c41d0
--output
json
\
|
jq
'.data.result.treatments[] | {treatmentKey, passRate: (if .failureRate == null then null else 1 - .failureRate end)}'
Find recurring failures for a task since July:
obss
results
analyze
find_failure_patterns
--task-key
checkout
--completed-after
2026-07-01T00:00:00Z
--output
json
Result fields
With
--output json
, the analysis is in
data.result
. The Baseline is the treatment that the experiment’s plan names as
referenceTreatmentClientId
. If none is marked,
compare_treatments
uses the first treatment.
Field
Mode
Meaning
totals.runs
,
totals.passedRuns
,
totals.failedRuns
summarize_scope
Runs in scope, and runs with a pass or a fail verdict
totals.evalsFailedRuns
,
totals.infraBlockedRuns
,
totals.inconclusiveRuns
,
totals.pendingRuns
summarize_scope
Runs with no verdict, by reason
treatments[].treatmentKey
,
runCount
,
passedRuns
,
failedRuns
summarize_scope
,
compare_treatments
The same counts for each treatment
treatments[].failureRate
compare_treatments
failedRuns / (passedRuns + failedRuns)
, or
null
when no run has a verdict
treatments[].isReferenceTreatment
compare_treatments
true
for the Baseline
treatments[].deltaFromReference.failureRate
compare_treatments
The treatment’s
failureRate
minus the Baseline’s
referenceTreatmentKey
compare_treatments
The
treatmentKey
of the Baseline
pendingRuns
summarize_scope
,
compare_treatments
Runs with no verdict that Evals can still judge
inconclusiveRuns
summarize_scope
,
compare_treatments
Runs with no verdict that Evals won’t judge. It leaves out
pendingRuns
.
insightsCoverage
summarize_scope
,
search_frictions
The runs split into
analyzedRuns
,
pendingRuns
, and
unanalyzedRuns
(Insights off, skipped, failed, or never run). An empty friction list is final when its
pendingRuns
is 0.
status
,
evalsPending
,
insightsPending
get_run_evidence
The run’s status, and whether its Evals or Insights result is still to come
page.truncated
,
page.reasons
Every mode
Whether the response was cut, and why:
row_limit
or
byte_limit
page.rankedCount
Every mode
How many items were ranked
page.completeData
Every mode
The complete read:
data.query
means
obss data query
with the named dataset, and
run.trajectory.read
means
obss runs trajectory
Notes
A pass rate is
passedRuns / (passedRuns + failedRuns)
, which is
1 - failureRate
. Runs that are blocked, inconclusive, or whose Evals failed have no verdict, so they stay out of both counts. Wait until
pendingRuns
is
0
, because the counts can still change until then.
--limit
is an upper bound, and the response size limit can return fewer items. The rows that
page.completeData
names can be finer than the ranked items, so check the hint before you compare counts. For how results become final, see
What Evals read
and
What Insights read
.
Next steps
obss frictions
List frictions with the same run scope flags.
obss evals and insights
Start Evals and Insights and page their results.
Read results
Matrix, Runs, and Compare in the dashboard.
CLI reference
Global flags, output, and exit codes.
schedules
frictions
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform