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

# Stream run events

> Read graph's progress as JSON events on stderr, for scripts, dashboards and CI annotations.

Set `GRAPH_EVENTS=jsonl` and graph writes its progress to stderr as one JSON object per line, instead of text for people. stdout still carries only the result, so you can read both from one run:

```bash theme={null}
GRAPH_EVENTS=jsonl graph plan run weekly_changes \
  --input base=v0.15.0 2> events.jsonl
```

The stream covers `graph plan run`, `graph ask` and `graph chat`. Every event has an `event` field naming its type.

```json Events on stderr theme={null}
{
  "event": "tool_started",
  "tool": "github__tool__git_log",
  "args": {
    "base": "v0.15.0",
    "head": "HEAD"
  }
}

{
  "event": "tool_finished",
  "tool": "github__tool__git_log",
  "ms": 41,
  "is_error": false
}

{
  "event": "synthesizing"
}

{
  "event": "model_call",
  "kind": "chat",
  "site": "solver",
  "model": "claude-sonnet-5-5",
  "input_tokens": 2140,
  "output_tokens": 388,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0,
  "ms": 5210
}

{
  "event": "usage_summary",
  "usage": {
    "calls": 1,
    "input_tokens": 2140,
    "output_tokens": 388,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "by_step": [],
    "by_model": [
      {
        "provider": "anthropic",
        "model": "claude-sonnet-5-5",
        "calls": 1,
        "input_tokens": 2140,
        "output_tokens": 388,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0
      }
    ]
  }
}
```

## Events

### tool\_started

A tool call began.

**tool** `string`

The tool's full name, such as `github__tool__git_log`.

**args** `object`

The input the tool was called with, after templates were filled.

### tool\_finished

A tool call ended.

**tool** `string`

The tool's full name.

**ms** `integer`

How long the call took, in milliseconds.

**is\_error** `boolean`

Whether the tool returned an error.

### agent\_round

An agent, or an `agent` step, started another round of model calls and tool calls.

**n** `integer`

The round number.

### synthesizing

A plan's `solver` started writing its answer.

### model\_call

A model call finished.

**kind** `enum\<string\>`

`chat` for a chat model, `decision` for a decision model.

**site** `string`

Where the call was made: the step's path, such as `E3` or `triage/E1`, or the model role when the call belongs to no step.

**model** `string`

The model id.

**input\_tokens** `integer`

Uncached input tokens.

**output\_tokens** `integer`

Output tokens.

**cache\_creation\_input\_tokens** `integer`

Input tokens written to the provider's prompt cache.

**cache\_read\_input\_tokens** `integer`

Input tokens read from the provider's prompt cache.

**ms** `integer`

How long the call took, in milliseconds.

### usage\_summary

What the whole run spent, sent once at the end, including when the run fails. graph skips it when the run made no model calls.

**usage.calls** `integer`

Model calls in the run.

**usage.input\_tokens** `integer`

Total uncached input tokens. `output_tokens`, `cache_creation_input_tokens` and `cache_read_input_tokens` sit alongside it.

**usage.cost\_usd** `number`

Total cost in USD. Present only when [`pricing`](/reference/configuration#param-pricing) covers a model the run used.

**usage.by\_step** `object[]`

The same totals per step, each with its `path`.

**usage.by\_model** `object[]`

The same totals per model, each with its `provider` and `model`.

## Related environment variables

**GRAPH\_EVENTS** `enum\<string\>`

How graph reports progress and failures on stderr. Unset, stderr is for people.

| Value | Effect |
| - | - |
| `jsonl` | stderr becomes a stream of JSON events, one per line. `ask` steps can't prompt anyone, so they use their `whenUnanswered` setting. |
| `github` | A failing `graph plan run` also prints a `::error::` annotation to stdout, which GitHub Actions shows on the run. |

[Go to full reference](/reference/environment-variables)


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