---
updatedAt: 2025-09-14T10:20:09.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 Goals
Search for Goals using filters and pagination parameters.
**Pagination parameters** are currently accepted but not enforced.
**Multiple filters** can be combined in a single request. All filters use AND logic (goals must match ALL specified filters).
**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/search": {
"post": {
"operationId": "post_goals-goals-search",
"tags": [
"Goals"
],
"summary": "Search Goals",
"description": "Search for Goals using filters and pagination parameters.
**Pagination parameters** are currently accepted but not enforced.
**Multiple filters** can be combined in a single request. All filters use AND logic (goals must match ALL specified filters).
\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": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoalsSearchRequest"
},
"examples": {
"single_status_filter": {
"summary": "Filter by single status",
"description": "Search for goals with a specific status",
"value": {
"fields": [
"id",
"title",
"status",
"owner",
"isPrivate"
],
"filters": [
{
"fieldId": "status",
"operator": "equals",
"values": [
"onTrack"
]
}
],
"limit": 25
}
},
"multiple_status_filter": {
"summary": "Filter by multiple statuses",
"description": "Search for goals with multiple status values",
"value": {
"fields": [
"id",
"title",
"status",
"owner",
"isPrivate"
],
"filters": [
{
"fieldId": "status",
"operator": "equals",
"values": [
"onTrack",
"completed",
"offTrack"
]
}
],
"limit": 25
}
},
"privacy_filter": {
"summary": "Filter by privacy setting",
"description": "Search for public goals only",
"value": {
"fields": [
"id",
"title",
"status",
"owner",
"isPrivate"
],
"filters": [
{
"fieldId": "isPrivate",
"operator": "equals",
"values": [
"false"
]
}
],
"limit": 25
}
},
"goal_type_filter": {
"summary": "Filter by goal type",
"description": "Search for goals of a specific type",
"value": {
"fields": [
"id",
"title",
"status",
"owner",
"typeId"
],
"filters": [
{
"fieldId": "typeId",
"operator": "equals",
"values": [
"5"
]
}
],
"limit": 25
}
},
"combined_filters": {
"summary": "Combined status, privacy, and type filters",
"description": "Search for active public goals of a specific type",
"value": {
"fields": [
"id",
"title",
"status",
"owner",
"isPrivate",
"typeId"
],
"filters": [
{
"fieldId": "status",
"operator": "equals",
"values": [
"onTrack",
"offTrack"
]
},
{
"fieldId": "isPrivate",
"operator": "equals",
"values": [
"false"
]
},
{
"fieldId": "typeId",
"operator": "equals",
"values": [
"5"
]
}
],
"limit": 50
}
}
}
}
}
},
"responses": {
"200": {
"description": "Goals details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponseGoals"
}
}
}
},
"400": {
"description": "Bad request with structured error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"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"
}
}
},
"GoalsSearchRequest": {
"type": "object",
"required": [
"fields"
],
"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.
\nLeave the filters empty to fetch all results.
\n**Goal filters**:
\n`status` - Filter goals by current status. Supports multiple values.
- **Values:** `onTrack`, `offTrack`, `completed`, `incomplete`, `other`
- **Example:** `[\"onTrack\", \"completed\"]`
\n`isPrivate` - Filter goals by privacy setting (public vs private goals).
- **Values:** `\"true\"` (private), `\"false\"` (public)
- **Example:** `[\"false\"]` for public goals only
\n`typeId` - Filter goals by goal type ID to show only goals of specific types.
- **Values:** Goal type ID as string (e.g., `\"1\"`, `\"5\"`, `\"42\"`)
- **Example:** `[\"5\"]` for goals of type ID 5\n",
"items": {
"type": "object",
"properties": {
"fieldId": {
"type": "string",
"description": "The field identifier to filter by.\n**Goal Filters:** `status`, `isPrivate`, `typeId`\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**Examples:**
- Status filter: `[\"onTrack\", \"completed\"]`
- Privacy filter: `[\"false\"]`
- Goal ID filter: `[\"123\"]`\n",
"items": {
"type": "string"
},
"example": [
"onTrack",
"completed"
]
}
}
}
},
"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"
}
}
},
"SearchResponseMetadata": {
"type": "object",
"properties": {
"totalCount": {
"type": "integer",
"format": "int64",
"description": "Total number of items available"
},
"pageSize": {
"type": "integer",
"description": "Number of items requested per page"
}
}
},
"SearchResponseGoals": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GoalSearchObject"
},
"description": "Array of items with enhanced structure"
},
"responseMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/SearchResponseMetadata"
},
{
"description": "Metadata about the search response"
}
]
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Cursor for next page (null if no more pages)"
},
"errors": {
"type": [
"object",
"null"
],
"description": "Error information if any"
}
}
},
"GoalSearchObject": {
"type": "object",
"properties": {
"objectType": {
"type": "string",
"description": "The type of the object",
"enum": [
"goal"
]
},
"fields": {
"type": "object",
"description": "Goal fields",
"properties": {
"id": {
"type": "object",
"description": "The backend id of the goal. Use this ID when querying key results of a specific goal, or when updating an existing goal.\n",
"properties": {
"value": {
"type": "integer",
"format": "int64",
"example": 1
}
}
},
"title": {
"type": "object",
"description": "The title of the goal",
"properties": {
"value": {
"type": "string",
"example": "Sample Title 1"
}
}
},
"description": {
"type": "object",
"description": "A brief description of the goal",
"properties": {
"value": {
"type": "string",
"example": "Sample description"
}
}
},
"startDate": {
"type": "object",
"description": "The start date of the goal",
"properties": {
"value": {
"type": "string",
"format": "date",
"example": "2025-01-01"
}
}
},
"dueDate": {
"type": "object",
"description": "The due date of the goal",
"properties": {
"value": {
"type": "string",
"format": "date",
"example": "2025-10-10"
}
}
},
"typeId": {
"type": "object",
"description": "The type ID of the goal",
"properties": {
"value": {
"type": "integer",
"format": "int64",
"example": 9292
}
}
},
"category": {
"type": "object",
"description": "The goal type category can be any of: `Company`, `Custom` (linked to a list in Bob) or `Individual`.\n",
"properties": {
"value": {
"type": "string",
"example": "Company"
}
}
},
"status": {
"type": "object",
"description": "The current status of the goal",
"properties": {
"value": {
"enum": [
"onTrack",
"offTrack",
"completed",
"incomplete",
"other"
],
"example": "completed"
}
}
},
"progress": {
"type": "object",
"description": "The average progress of the goal (percentage)",
"properties": {
"value": {
"type": "number",
"format": "double",
"example": 75
}
}
},
"owner": {
"type": "object",
"description": "The owner of the goal. Must be an existing owner identifier\n",
"properties": {
"value": {
"type": "string",
"example": "123123123"
}
}
},
"isPrivate": {
"type": "object",
"description": "Whether the goal is private",
"properties": {
"value": {
"type": "boolean",
"example": false
}
}
},
"alignedGoal": {
"type": "object",
"description": "The ID of the goal this goal is aligned to (if any)",
"properties": {
"value": {
"type": "integer",
"format": "int64",
"example": 9797
}
}
},
"hasKeyResults": {
"type": "object",
"description": "Whether the goal has key results",
"properties": {
"value": {
"type": "boolean",
"example": true
}
}
},
"isActive": {
"type": "object",
"description": "Whether the goal is active (status is `onTrack` or `offTrack`)\n",
"properties": {
"value": {
"type": "boolean",
"example": false
}
}
},
"cycleId": {
"type": "object",
"description": "The ID of the cycle this goal is assigned to (if any)",
"properties": {
"value": {
"type": "integer",
"format": "int64",
"example": 456
}
}
},
"weight": {
"type": "object",
"description": "Indicates the weight or percentage of this goal within its cycle. This field is read-only. Weights are automatically and equally distributed across all goals in an employee’s cycle. Custom weight assignment is not supported via public APIs.\n",
"properties": {
"value": {
"type": "number",
"format": "double",
"example": 25.5
}
}
}
}
}
}
}
},
"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."
}
}
}
}
```