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

# Find execution by agent id

Use Execution Context Search when you know a business value but do not know the execution ID.

For example, you may know:

* customer ID
* user ID
* request ID
* order ID
* transaction ID
* reference number
* response status
* provider reference

Foveus can use indexed context fields to find the execution that contains that value.

## Example

A customer contacts support and says their order failed.

You know:

| Detail           | Value        |
| ---------------- | ------------ |
| Service          | `orders-api` |
| Customer ID      | `cus_12345`  |
| Approximate time | Today        |

Search:

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

This returns executions from `orders-api` where Foveus indexed `customerId = cus_12345`.

## Query format

Use the `context:` token.

```text theme={null}
context:<key>=<value>
```

For example:

```text theme={null}
context:customerId="cus_12345"
```

When you know the service, include it:

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

Adding a service filter keeps the search faster and more precise.

## Use quotes for strings

String values should use quotes.

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

```text theme={null}
service:orders-api context:request_id="req_12345"
```

Numbers do not need quotes.

```text theme={null}
service:orders-api context:orderStatus.value=1
```

Booleans do not need quotes.

```text theme={null}
service:orders-api context:isPriority=true
```

## Search by request ID

If your service captures request IDs, search by request ID.

```text theme={null}
service:orders-api context:request_id="req_12345"
```

Foveus normalizes common key styles, so these can resolve to the same indexed key when captured:

```text theme={null}
requestId
request_id
request-id
```

This helps when different teams or providers use different naming conventions.

## Search by nested values

Use dotted paths for nested context.

Given this response:

```json theme={null}
{
  "orderStatus": {
    "value": 2,
    "label": "Failed"
  }
}
```

Search by numeric value:

```text theme={null}
service:orders-api context:orderStatus.value=2
```

Search by label:

```text theme={null}
service:orders-api context:orderStatus.label="Failed"
```

## Search by multiple values

Use commas when you want to search for more than one value for the same key.

```text theme={null}
service:orders-api context:customerId="cus_12345","cus_67890"
```

Values for the same key use **OR**.

This means:

```text theme={null}
customerId is cus_12345 OR cus_67890
```

## Search by multiple keys

Use multiple `context:` tokens when you want all conditions to match.

```text theme={null}
service:orders-api context:customerId="cus_12345" context:orderStatus.value=2
```

Different keys use **AND**.

This means:

```text theme={null}
customerId is cus_12345
AND
orderStatus.value is 2
```

## Add status when needed

If you are looking for a failure, add `status:failed`.

```text theme={null}
service:orders-api status:failed context:customerId="cus_12345"
```

This narrows the search to failed executions for that customer.

## Add endpoint when known

If you know the endpoint, add it.

```text theme={null}
service:orders-api method:POST endpoint:/orders context:customerId="cus_12345"
```

This is useful when the same business ID appears across multiple endpoints.

## What Foveus searches

Foveus searches indexed execution context.

Context can come from:

* request query
* request body
* response body
* custom context

Foveus does not scan arbitrary raw request or response bodies.

## If no result appears

Check the following:

### The service name matches

Search by the service name shown in Foveus.

```text theme={null}
service:orders-api
```

If your organization uses environment-specific service names, search by the actual name your service sends.

```text theme={null}
service:orders-api-prod
```

### The value is quoted if it is a string

Use:

```text theme={null}
context:customerId="cus_12345"
```

not:

```text theme={null}
context:customerId=cus_12345
```

### The value was captured

Open a nearby execution and confirm the request or response context includes the value.

### The field was indexed

Execution Context Search only works on indexed context fields.

If indexing settings changed recently, trigger a new request and search again.

### The route was not excluded

If the endpoint is excluded by SDK configuration, Foveus may not capture the execution or context.

Check:

```json theme={null}
{
  "Foveus": {
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

### The execution is still within retention

Searchable context follows execution retention.

If the execution expired, its searchable context expires too.

## Recommended workflow

1. Start with `service:`.
2. Add the business ID with `context:`.
3. Add `status:failed` if you are investigating a failure.
4. Add `method:` and `endpoint:` if you know the route.
5. Open the execution.
6. Inspect response context, timeline, and logs.

## More examples

Find by customer ID:

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

Find by user ID:

```text theme={null}
service:orders-api context:userId="usr_12345"
```

Find by request ID:

```text theme={null}
service:orders-api context:request_id="req_12345"
```

Find by transaction ID:

```text theme={null}
service:payments-api context:transactionId="txn_12345"
```

Find failed executions for an order:

```text theme={null}
service:orders-api status:failed context:orderId="ord_12345"
```

Find an execution with a confirmed order status:

```text theme={null}
service:orders-api context:orderStatus.label="Confirmed"
```

## What to do next

* Learn about context search: [Execution Context Search](/concepts/execution-context-search)
* View your first execution: [View your first execution](/get-started/view-your-first-execution)
* Investigate a user complaint: [Investigate a user complaint](/guides/investigate-user-complaint)
* Review data safety: [Data safety and retention](/security/data-safety-and-retention)