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:

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.

context:<key>=<value>

For example:

context:customerId="cus_12345"

When you know the service, include it:

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.

service:orders-api context:customerId="cus_12345"

service:orders-api context:request_id="req_12345"

Numbers do not need quotes.

service:orders-api context:orderStatus.value=1

Booleans do not need quotes.

service:orders-api context:isPriority=true

Search by request ID

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

service:orders-api context:request_id="req_12345"

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

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:

{
  "orderStatus": {
    "value": 2,
    "label": "Failed"
  }
}

Search by numeric value:

service:orders-api context:orderStatus.value=2

Search by label:

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.

service:orders-api context:customerId="cus_12345","cus_67890"

Values for the same key use OR. This means:

customerId is cus_12345 OR cus_67890

Search by multiple keys

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

service:orders-api context:customerId="cus_12345" context:orderStatus.value=2

Different keys use AND. This means:

customerId is cus_12345
AND
orderStatus.value is 2

Add status when needed

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

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.

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.

service:orders-api

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

service:orders-api-prod

The value is quoted if it is a string

Use:

context:customerId="cus_12345"

not:

context:customerId=cus_12345

The value was captured

Open a nearby execution and confirm the request or response context includes the value. Context is captured for every failed request, but only for a sample of successful requests (1% by default, set by ContextSamplingRate). Response bodies are not captured by default.

The field was indexed

Execution Context Search only works on indexed context fields. Foveus does not index or search keys that are, or contain, sensitive words such as password, token, secret, card or pin, or values that look like tokens. Fields redacted by the SDK, such as email or phone, are stored as ***. See Sensitive 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:

{
  "Foveus": {
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

The context is still retained

Executions and their searchable context properties are kept for 2 days during private beta. Context search cannot find an execution after that. See Data safety and retention.

Recommended workflow

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

More examples

Find by customer ID:

service:orders-api context:customerId="cus_12345"

Find by user ID:

service:orders-api context:userId="usr_12345"

Find by request ID:

service:orders-api context:request_id="req_12345"

Find by transaction ID:

service:payments-api context:transactionId="txn_12345"

Find failed executions for an order:

service:orders-api status:failed context:orderId="ord_12345"

Find an execution with a confirmed order status:

service:orders-api context:orderStatus.label="Confirmed"

What to do next

Learn about context search: Execution Context Search
View your first execution: View your first execution
Investigate a user complaint: Investigate a user complaint
Review data safety: Data safety and retention

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference