---
updatedAt: 2025-09-14T10:19:58.000Z
---
Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.
# Search Key Results
Search for Key Results of a specific Goals, using filters. The `goalId` filter is mandatory.
**Note: Pagination parameters are currently accepted but not enforced.**
**Testing notes:**
- Use the testing widget's **Try It!** option to test this endpoint.
- Use the **Examples > Request Example** option to see how to initiate body parameters.
**Testing notes**:
1. Use the testing widget's **Try It!** option to test this endpoint.
2. Use the **Examples > Request Example** option to see how to initiate body parameters.
# OpenAPI definition
```json
{
"openapi": "3.1.1",
"info": {
"title": "Goals API",
"description": "Public API for managing Goal Types, Goals, and Key Results with clean entity separation.",
"license": {
"name": "Proprietary",
"url": "https://apidocs.hibob.com/docs/api-terms-of-use"
},
"contact": {
"name": "Hi Bob, Inc."
},
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.hibob.com/v1",
"description": "Production"
},
{
"url": "https://api.sandbox.hibob.com/v1",
"description": "Sandbox"
}
],
"x-readme": {
"metrics-enabled": false
},
"tags": [
{
"name": "Goals",
"description": "Operations for managing Goal Types, Goals, and Key Results"
}
],
"paths": {
"/goals/goals/key-results/search": {
"post": {
"operationId": "post_goals-goals-key-results-search",
"tags": [
"Goals"
],
"summary": "Search Key Results",
"description": "Search for Key Results of a specific Goals, using filters. The `goalId` filter is mandatory.
**Note: Pagination parameters are currently accepted but not enforced.**
\n**Testing notes:**
- Use the testing widget's **Try It!** option to test this endpoint.
- Use the **Examples > Request Example** option to see how to initiate body parameters.
\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KeyResultSearchRequest"
},
"example": {
"fields": [
"id",
"title",
"measureType",
"currentValue",
"target",
"startValue"
],
"filters": [
{
"fieldId": "goalId",
"operator": "equals",
"values": [
"123"
]
}
],
"limit": 50
}
}
}
},
"responses": {
"200": {
"description": "The key results of a given goal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponseKeyResult"
}
}
}
},
"400": {
"description": "Bad request with structured error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
},
"example": {
"error": "BAD_REQUEST",
"message": "goalId filter is mandatory for key-results search",
"statusCode": 400,
"timestamp": "2025-01-01T12:00:00Z"
}
}
}
},
"429": {
"description": "Rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"Basic": []
},
{
"Bearer": []
}
]
}
}
},
"components": {
"schemas": {
"ApiErrorResponse": {
"type": "object",
"required": [
"error",
"message",
"statusCode",
"timestamp"
],
"properties": {
"error": {
"type": "string",
"description": "Error type identifier",
"enum": [
"BAD_REQUEST",
"NOT_FOUND",
"INTERNAL_SERVER_ERROR",
"TOO_MANY_REQUESTS",
"UNAUTHORIZED",
"FORBIDDEN"
],
"example": "BAD_REQUEST"
},
"message": {
"type": "string",
"description": "Human-readable error message",
"example": "Invalid input provided"
},
"statusCode": {
"type": "integer",
"description": "HTTP status code",
"enum": [
400,
401,
403,
404,
429,
500
],
"example": 400
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO timestamp when the error occurred",
"example": "2025-01-01T12:00:00Z"
}
}
},
"KeyResultSearchRequest": {
"type": "object",
"required": [
"fields",
"filters"
],
"properties": {
"fields": {
"type": "array",
"description": "List of fields IDs to include in the response. Use the metadata endpoints to fetch the available fields.\n",
"items": {
"type": "string"
}
},
"filters": {
"type": "array",
"description": "List of filters to apply to the search. Multiple filters use AND logic.
\nKey Result Filters:
\n`goalId` - Required for Key Results
Mandatory filter to specify which goal's key results to retrieve.
- **Values:** Goal ID as string
- **Example:** `[\"123\"]`\n",
"items": {
"type": "object",
"properties": {
"fieldId": {
"type": "string",
"description": "The field identifier to filter by.\n**Key Result Filters:** `goalId` (required), `measureType`, `title`\n",
"example": "status"
},
"operator": {
"type": "string",
"description": "The operator to use for the filter. Currently only `equals` is supported for all filters.\n",
"enum": [
"equals"
],
"default": "equals"
},
"values": {
"type": "array",
"description": "The values to use for the filter. Multiple values are treated as OR within the same filter.\n**Example:** - Goal ID filter: `[\"123\"]`\n",
"items": {
"type": "string"
},
"example": [
"goalId"
]
}
}
}
},
"limit": {
"type": "integer",
"description": "Maximum number of results to return (Note: pagination parameters are currently accepted but not enforced).\n"
},
"cursor": {
"type": "string",
"description": "Cursor for pagination (Note: pagination parameters are currently accepted but not enforced).\n"
}
}
},
"KeyResultObject": {
"type": "object",
"properties": {
"objectType": {
"type": "string",
"enum": [
"keyResult"
]
},
"fields": {
"type": "object",
"properties": {
"id": {
"type": "object",
"properties": {
"value": {
"type": "integer",
"format": "int64"
}
}
},
"title": {
"type": "object",
"properties": {
"value": {
"type": "string"
}
}
},
"goalId": {
"type": "object",
"properties": {
"value": {
"type": "integer",
"format": "int64",
"description": "The ID of the goal this key result belongs to"
}
}
},
"measureType": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"numeric",
"boolean",
"percentage",
"currency"
]
}
}
},
"target": {
"type": "object",
"properties": {
"value": {
"description": "Target value - number for numeric/currency/percentage measures, boolean for boolean measures",
"oneOf": [
{
"type": "number"
},
{
"type": "boolean"
}
]
}
}
},
"startValue": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "The baseline start value for this key result. Applies to numeric, percentage, and currency measures. Depending on how the key result is defined, the target can be ascending or descending, so the start value can be lower or higher than the target value."
}
}
},
"currentValue": {
"type": "object",
"properties": {
"value": {
"description": "Current value - number for numeric/currency/percentage measures, boolean for boolean measures",
"oneOf": [
{
"type": "number"
},
{
"type": "boolean"
}
]
}
}
},
"currency": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "The currency code (e.g., 'USD', 'EUR', 'GBP'). Returned only for currency-type key results"
}
}
},
"currencySymbol": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "The currency symbol (e.g., '$', '€', '£'). Returned only for currency-type key results"
}
}
},
"progress": {
"type": "object",
"properties": {
"value": {
"type": "number",
"format": "double"
}
}
}
}
}
}
},
"SearchResponseKeyResult": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KeyResultObject"
}
}
}
}
},
"securitySchemes": {
"Basic": {
"type": "http",
"scheme": "basic"
},
"Bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "OAuth 2.0",
"description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow these steps to complete the OAuth 2.0 flow in Postman and then paste the token here."
}
}
}
}
```