# 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 |
View JSON Schema
**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"
}
```
## Output Parameters
| Name | Type | Description |
| ----- | ------ | -------------------------------------- |
| value | object | The matched value object from the data |
View JSON Schema
```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"
}
```
## 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.agenticflow.ai/reference/nodes/get_value_by_key.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.