> For the complete documentation index, see [llms.txt](https://docs.agenticflow.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agenticflow.ai/reference/nodes/get_value_by_key.md).

# Get Value by Key

**Action ID:** `get_value_by_key`

## Description

Get a value from a data object by key.

## Input Parameters

| Name             | Type   | Required | Default | Description                                     |
| ---------------- | ------ | :------: | ------- | ----------------------------------------------- |
| data             | string |     ✓    | -       | The data object (JSON) to get the value from    |
| key\_to\_match   | string |     ✓    | -       | The key field to search for in the data objects |
| value\_to\_match | string |     ✓    | -       | The value to match in the specified key field   |

<details>

<summary>View JSON Schema</summary>

**Input Schema**

```json
{
  "description": "Get value by key node input.",
  "properties": {
    "data": {
      "description": "The data object to get the value from.",
      "title": "Data Object",
      "type": "string"
    },
    "key_to_match": {
      "description": "The key field to search for in the data objects.",
      "title": "Key to Match",
      "type": "string"
    },
    "value_to_match": {
      "description": "The value to match in the specified key field.",
      "title": "Value to Match",
      "type": "string"
    }
  },
  "required": [
    "data",
    "key_to_match",
    "value_to_match"
  ],
  "title": "GetValueByKeyNodeInput",
  "type": "object"
}
```

</details>

## Output Parameters

| Name  | Type   | Description                            |
| ----- | ------ | -------------------------------------- |
| value | object | The matched value object from the data |

<details>

<summary>View JSON Schema</summary>

```json
{
  "description": "Get value by key node output.",
  "properties": {
    "value": {
      "additionalProperties": true,
      "description": "The value from the data object.",
      "title": "Value",
      "type": "object"
    }
  },
  "required": [
    "value"
  ],
  "title": "GetValueByKeyNodeOutput",
  "type": "object"
}
```

</details>

## How It Works

This node searches through a data object (typically a JSON array or object) to find an entry where a specified key matches a specified value. It acts as a filter or lookup function, scanning through the data structure to locate and return the complete object/entry that contains the matching key-value pair. This is particularly useful for extracting specific records from datasets or API responses.

## Usage Examples

### Example 1: Find User by ID

**Input:**

```
data: '[{"id": "user123", "name": "John Doe", "email": "john@example.com"}, {"id": "user456", "name": "Jane Smith", "email": "jane@example.com"}]'
key_to_match: "id"
value_to_match: "user456"
```

**Output:**

```
value: {
  "id": "user456",
  "name": "Jane Smith",
  "email": "jane@example.com"
}
```

### Example 2: Find Product by SKU

**Input:**

```
data: '[{"sku": "ABC123", "name": "Widget", "price": 29.99}, {"sku": "XYZ789", "name": "Gadget", "price": 49.99}]'
key_to_match: "sku"
value_to_match: "ABC123"
```

**Output:**

```
value: {
  "sku": "ABC123",
  "name": "Widget",
  "price": 29.99
}
```

### Example 3: Find Customer Segment by Status

**Input:**

```
data: '[{"status": "active", "count": 150, "revenue": 50000}, {"status": "inactive", "count": 45, "revenue": 5000}]'
key_to_match: "status"
value_to_match: "active"
```

**Output:**

```
value: {
  "status": "active",
  "count": 150,
  "revenue": 50000
}
```

## Common Use Cases

* **Database Lookups**: Find specific records from datasets based on unique identifiers like IDs or keys
* **API Response Filtering**: Extract relevant objects from API responses containing arrays of data
* **User Data Retrieval**: Locate user profiles or accounts by username, email, or ID
* **Product Catalog Search**: Find specific products or items by SKU, category, or other attributes
* **Configuration Management**: Retrieve specific configuration settings from complex configuration objects
* **Data Transformation**: Extract and pass specific data subsets to subsequent workflow nodes
* **Conditional Routing**: Use matched values to determine workflow paths or decision logic

## Error Handling

| Error Type       | Cause                                                        | Solution                                                                         |
| ---------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Invalid JSON     | Data parameter contains malformed JSON                       | Ensure data is valid JSON format before passing to this node                     |
| Key Not Found    | The specified key doesn't exist in any data objects          | Verify the key\_to\_match exactly matches keys in your data structure            |
| No Match Found   | No objects contain the specified key-value pair              | Check that value\_to\_match exists in your dataset or handle empty results       |
| Type Mismatch    | value\_to\_match type doesn't match the data type in objects | Ensure value\_to\_match matches the data type (string, number, etc.)             |
| Empty Data       | Data parameter is empty or null                              | Validate that upstream nodes are providing data before this node                 |
| Multiple Matches | Multiple objects match the criteria                          | This node returns the first match; refine your key-value criteria for uniqueness |

## Notes

* **First Match Only**: If multiple objects match the key-value pair, only the first matching object is returned.
* **Case Sensitivity**: The value matching is case-sensitive. "Active" and "active" are treated as different values.
* **Data Format**: The data parameter should be a JSON string representing an array of objects or a single object.
* **Exact Matching**: The node performs exact string matching on the value. Partial matches are not supported.
* **Nested Objects**: For nested data structures, specify the exact key path or consider using JSON path expressions.
* **Performance**: For large datasets, consider filtering data upstream to reduce processing time.
* **Error Handling**: If no match is found, the node may return null or an empty object. Handle these cases in subsequent nodes.