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

# Values

> The two tools that return captured bytes: one trace's slots by path, and up to five worked examples of a function.

Two tools return the bytes a marked function actually saw. `vexlo_get_values` fetches named
slots on named steps of one trace. `vexlo_get_function_examples` fetches up to five real
executions of one function. Reach them with a `path` from
[`vexlo_get_trace`](https://docs.vexlo.ai/mcp/tools/shape) or a name from [find](https://docs.vexlo.ai/mcp/tools/find.md), and only where a
preview looks worth reading in full.

Every response below comes from the seeded server [find](https://docs.vexlo.ai/mcp/tools/find.md) describes: the spec's
conformance trace on team `fixture`, with one three-attempt step.

## vexlo\_get\_values

| Argument | Type | Default |
| - | - | - |
| `traceId` | the trace to read | required |
| `path` | 1 to `values_max_paths` opaque paths, 8 on this server | required |
| `slots` | any of `input`, `output`, `error`, `logs` | every slot present on each named step |

A `path` is a step's identity and is opaque. Copy it verbatim from `vexlo_get_trace`: never
construct, decode, or guess one. The path ceiling is the API's own hard limit, read from the
server's `limits` rather than hardcoded, so the tool's description always carries the number
that field reports. Call again for more paths. Omitting `slots` returns every slot the step
has, so a step with no `error` slot has none to return.

The root step's path is the empty string, which is a real path:

```json theme={null}
{
  "values": [
    {
      "path": "",
      "slot": "error",
      "state": "stored",
      "encoding": "json",
      "value": "{\"message\":\"no eligible candidate in list\",\"stack\":[\"assign_dasher_handler.py:8\",\"assign_dasher.py:20\"]}",
      "bytes_count": 104,
      "truncated": false
    },
    {
      "path": "",
      "slot": "input",
      "state": "stored",
      "encoding": "json",
      "value": "{\"method\":\"POST\",\"order_id\":\"O-1234\",\"path\":\"/delivery/assign-dasher\"}",
      "bytes_count": 70,
      "truncated": false
    }
  ],
  "unknown_paths": []
}
```

`value` is always a string, and `encoding` says how to read it: `json` is canonical JSON text
to parse, `text` the captured string itself, `base64` binary bytes to decode first.

`state` and the presence of `value` are independent. A slot reads `state: "pending"` and still
carries a real `value`, as the step below does, when the value record shipped in the same batch
as the shape before this trace's sampling fate was settled, and reads `state: "pending"` with
no `value` when nothing has shipped yet. Branch on whether
`value` is present, never on the `state` string:

```json theme={null}
{
  "values": [
    {
      "path": "AACAAAA",
      "slot": "input",
      "state": "pending",
      "encoding": "json",
      "value": "{\"radius_km\":5,\"requested_time\":\"19:30\",\"zone\":\"SF-94107\"}",
      "bytes_count": 58,
      "truncated": false
    },
    {
      "path": "AACAAAA",
      "slot": "output",
      "state": "pending",
      "encoding": "json",
      "value": "{\"dashers\":[],\"eligible_dashers\":0,\"query_latency_ms\":192}",
      "bytes_count": 58,
      "truncated": false
    }
  ],
  "unknown_paths": []
}
```

`state` is an open string: the nine states [conventions](https://docs.vexlo.ai/api/conventions.md) documents are what the
server emits today, and an unrecognised one passes through rather than failing the call. Three
mean the bytes never existed, so asking again cannot produce them: `redacted`, `too_large`, and
`not_captured`. A slot that resolves to `expired` at read time arrives with `path`, `slot`, and
`state` only ([traces](https://docs.vexlo.ai/api/traces.md)); a value record that never shipped reads `expired` too, not
`missing`.

A path that matches no step in the trace is not an error. It comes back in `unknown_paths`, in the
server's canonical spelling. Count its entries rather than matching them to what you sent: a
mistyped path is named as what it decoded to. Here `AAZZZZZ` was asked for alongside a real
path and came back as `AAZZZZY`:

```json theme={null}
{
  "values": [
... 18 lines omitted
  ],
  "unknown_paths": [
    "AAZZZZY"
  ]
}
```

A third answer is neither: no entries, and the path absent from `unknown_paths` too. Read that
as a path the trace has with no slot to read only for a path `vexlo_get_trace` returned in
`steps`; for any other string it is as likely a path this trace never had. Two situations
produce it, a step whose attempts are all still in flight and a completed attempt that captured
no slot, so read the attempt's own `status` in [`vexlo_get_trace`](https://docs.vexlo.ai/mcp/tools/shape) to tell
them apart. Neither is `state: "not_captured"`, which is a slot that is present and says so.

A retried step returns one entry per attempt, each with the same `path` and `slot`, in attempt
order. Nothing names the attempt, so the only way to pair entries with attempts is the order
`vexlo_get_trace` lists them in. This step failed three times with the same error:

```json theme={null}
{
  "values": [
    {
      "path": "AACAAAIAAA",
      "slot": "error",
      "state": "stored",
      "encoding": "json",
      "value": "{\"message\":\"no eligible candidate in list\",\"stack\":[\"select_eligible_dasher.py:44\",\"pick_best_from_candidates.py:12, in PickBestFromCandidates()\"]}",
      "bytes_count": 147,
      "truncated": false
    },
... 18 lines omitted
  ],
  "unknown_paths": []
}
```

Cost tracks the bytes captured, not the number of paths asked for. Over the one-line text each
call returned, of which the blocks above are `jq .` renderings, the root's two slots are 444
bytes and 121 tokens, one step's two slots 396 bytes and 113
tokens, the three error entries above 859 bytes and 234 tokens, and the root plus the first
seven steps in path order, eight paths in one call, 2,788 bytes and 806 tokens.

## vexlo\_get\_function\_examples

Returns up to five real executions of one function: the trace id, the path, the attempt, when
it ran, whether it succeeded, and a preview of its `input` and `output`.

| Argument | Type | Default |
| - | - | - |
| `service` | the service the function belongs to | required |
| `name` | exact `module.qualname` | required |
| `includeValues` | boolean | `false` |
| `limit` | 1 to 5 | 5 |
| `team` | array of team ids | every team in the token's set |
| `environment` | `{named}` or `{unset}` | no filter |

`team` and `environment` are as [find](https://docs.vexlo.ai/mcp/tools/find.md) defines them: `environment` takes
`{"named": [...]}` or `{"unset": true}` and nothing else.

There is no cursor. The function index keeps at most five example ids per `(service, name)`,
combined across every environment the function has run in, so asking again returns the same
five. `team` and `environment` filter those five, never a wider pool. `started_at` is when the
example was ingested, not when the trace ran, which [functions](https://docs.vexlo.ai/api/functions.md) explains.

```json theme={null}
{
  "function": {
    "service": "delivery-service",
    "name": "delivery.dispatch.PickBestFromCandidates"
  },
  "examples": [
    {
      "trace_id": "0f1a2b3c4d5e6f708192a3b4c5d6e7f8",
      "path": "AACAAAIAAA",
      "attempt": 0,
      "started_at": "2026-11-05T05:51:22.988Z",
      "status": "error",
      "input": {
        "state": "stored",
        "bytes_count": 116,
        "truncated": false,
        "encoding": "json",
        "preview": "{\"candidate_ids\":[\"D-101\",\"D-102\",\"D-103\",\"D-104\",\"D-105\"],\"radi"
      },
      "output": {
        "state": "not_captured",
        "truncated": false
      }
    }
  ]
}
```

`includeValues: true` replaces every example's preview with its complete stored value, the only
widening parameter in the read surface. The preview response above is 466 bytes and 158 tokens,
the widened one 525 bytes and 179 tokens: the same example with its 116-byte input in full
rather than 64 code points of it.

```json theme={null}
{
  "function": {
    "service": "delivery-service",
    "name": "delivery.dispatch.PickBestFromCandidates"
  },
  "examples": [
    {
      "trace_id": "0f1a2b3c4d5e6f708192a3b4c5d6e7f8",
      "path": "AACAAAIAAA",
      "attempt": 0,
      "started_at": "2026-11-05T05:51:22.988Z",
      "status": "error",
      "input": {
        "state": "stored",
        "bytes_count": 116,
        "truncated": false,
        "encoding": "json",
        "value": "{\"candidate_ids\":[\"D-101\",\"D-102\",\"D-103\",\"D-104\",\"D-105\"],\"radius_km\":5,\"requested_time\":\"19:30\",\"zone\":\"SF-94107\"}"
      },
      "output": {
        "state": "not_captured",
        "truncated": false
      }
    }
  ]
}
```

A handle carries `preview` or `value`, never both: the widened form drops the preview.

The `output` slot above reads `not_captured` because this tool rewrote it. The route renders a
slot the example does not carry as the zero value of its handle type, an empty `state` that is
not one of the documented states:

```
$ curl -s -H "Authorization: Bearer $READ_TOKEN" \
    "http://127.0.0.1:18300/v1/functions/examples?team=fixture&service=delivery-service&name=delivery.dispatch.PickBestFromCandidates" \
    | jq '.examples[0].output'
{
  "state": "",
  "truncated": false
}
```

The tool maps that empty string to `not_captured`, and its description tells an AI agent to
read an absent `input` or `output` key the same way: this attempt carried no such slot. The
mapping is a workaround, not a promise: the same empty `state` appears on a successful attempt
as on this failed one. The API's other two routes leave an absent slot out entirely, as the
spec's conformance case requires.


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