> ## 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.

# Search nested response context

Use nested context search when the value you need is inside a structured response object.

This is useful when your service or a third-party provider returns a business outcome in the response body.

For example:

```json theme={null}
{
  "orderStatus": {
    "value": 1,
    "label": "Confirmed"
  },
  "paymentStatus": {
    "value": 2,
    "label": "Pending"
  }
}
```

Foveus can index safe scalar fields from this response.

Then you can search:

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

or:

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

## When to use this

Use nested response context search when you know a value returned by your API or provider.

Examples:

* order status
* payment status
* provider response code
* verification result
* approval status
* shipment status
* risk decision
* workflow result

This helps you find executions without manually searching logs.

## Query format

Use `context:` with a dotted path.

```text theme={null}
context:<object>.<field>=<value>
```

Example:

```text theme={null}
context:orderStatus.value=1
```

When you know the service, include it:

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

Adding `service:` keeps the search faster and more precise.

## Strings need quotes

Use quotes for string values.

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

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:isApproved=true
```

## Example: search by response status

Given this response:

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

Search by value:

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

Search by label:

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

## Example: search by provider response

Given this response:

```json theme={null}
{
  "provider": {
    "name": "delivery-provider",
    "status": {
      "code": "PENDING_PICKUP",
      "message": "Package is waiting for pickup"
    }
  }
}
```

Search by provider status code:

```text theme={null}
service:orders-api context:provider.status.code="PENDING_PICKUP"
```

Search by provider name:

```text theme={null}
service:orders-api context:provider.name="delivery-provider"
```

## Example: search by boolean result

Given this response:

```json theme={null}
{
  "riskDecision": {
    "approved": false,
    "reason": "manual_review_required"
  }
}
```

Search for rejected decisions:

```text theme={null}
service:orders-api context:riskDecision.approved=false
```

Search by reason:

```text theme={null}
service:orders-api context:riskDecision.reason="manual_review_required"
```

## Arrays of objects

If a response contains an array of objects, Foveus can index safe scalar child fields when array extraction is enabled.

Given this response:

```json theme={null}
{
  "statuses": [
    { "value": 1, "label": "Confirmed" },
    { "value": 2, "label": "Failed" }
  ]
}
```

Foveus can index:

```text theme={null}
statuses.value = 1
statuses.label = Confirmed
statuses.value = 2
statuses.label = Failed
```

Then you can search:

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

or:

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

<Note>
  For arrays, matching is existence-based. `context:statuses.value=1` means at least one item in the array has `value = 1`.
</Note>

## Multiple nested fields

You can combine multiple context filters.

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

Different context keys use **AND**.

This means both indexed values must exist on the execution.

## Search with status

Add `status:failed` when you only want failed executions.

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

This is useful when the same response value appears in both successful and failed flows.

## Search with endpoint

Add `endpoint:` when you know the route.

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

This is useful when the same response structure appears across multiple endpoints.

## How Foveus indexes nested fields

Foveus indexes safe scalar fields from enabled context sources.

For response context, nested objects become dotted paths.

```json theme={null}
{
  "orderStatus": {
    "value": 1,
    "label": "Confirmed"
  }
}
```

becomes:

```text theme={null}
orderStatus.value = 1
orderStatus.label = Confirmed
```

Foveus does not index every possible payload blindly. It applies safety controls before indexing.

## Safety controls

Foveus applies controls such as:

* redaction
* sensitive-key denylist
* scalar-only indexing
* maximum value length
* maximum traversal depth
* maximum indexed properties per execution
* allowed context sources
* sampling and retention controls

Sensitive values should not be indexed.

## If no result appears

Check:

* the service name matches the execution service
* the time range includes the execution
* response body capture is enabled
* the response value is scalar
* the route was not excluded
* the value was not redacted
* the field was indexed after context indexing was enabled
* the field is still within retention
* the string value is quoted

For example:

```text theme={null}
context:orderStatus.label="Confirmed"
```

not:

```text theme={null}
context:orderStatus.label=Confirmed
```

## Recommended workflow

1. Start with the service.
2. Add the nested response field.
3. Add endpoint or method if known.
4. Add `status:failed` if investigating failures.
5. Open the matching execution.
6. Inspect response context and timeline.
7. Check linked logs or issues if available.

## Useful examples

Find confirmed orders:

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

Find failed order responses:

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

Find pending provider responses:

```text theme={null}
service:orders-api context:provider.status.code="PENDING_PICKUP"
```

Find rejected risk decisions:

```text theme={null}
service:orders-api context:riskDecision.approved=false
```

Find failed executions with a provider status:

```text theme={null}
service:orders-api status:failed context:provider.status.code="TIMEOUT"
```

## What to do next

* Learn about context search: [Execution Context Search](/concepts/execution-context-search)
* Find an execution by business ID: [Find an execution by business ID](/guides/find-execution-by-agent-id)
* Investigate a user complaint: [Investigate a user complaint](/guides/investigate-user-complaint)
* Configure redaction: [Redaction](/sdk/redaction)