---
title: "(BETA) Semantic Search in Metadata"
method: POST
path: "/api/v1/ai/workspaces/{workspace_id}/search"
tags: ["Smart Functions"]
---

# (BETA) Semantic Search in Metadata

`POST /api/v1/ai/workspaces/{workspace_id}/search`

## Request

- Base URL: `https://www.gooddata.ai`
- URL: `https://www.gooddata.ai/api/v1/ai/workspaces/{workspace_id}/search`
- Auth: none declared

(BETA) Uses similarity (e.g. cosine distance) search to find top X most similar metadata objects.

## Path parameters

- `workspace_id` string, required

## Request body

- SearchRequest
  - `allowedRelationshipTypes` SearchAllowedRelationshipType[]: Filter relationships and results based on allowed relationship type combinations. When specified, only relationships matching the allowed types are returned, and results are filtered to include only direct matches or objects reachable via allowed relationships. When null or omitted, all relationships and results are returned (default behavior). Note: This filtering happens after the initial search, so the number of returned results may be lower than the requested limit if some results are filtered out.
    - `allowOrphans` boolean: If true, allows target objects that are not part of any relationship (orphans) to be included in results. If false, orphan target objects will be excluded even if they directly match the search query. Default is true (orphans are allowed).
    - `sourceType` 'attribute' | 'metric' | 'fact' | 'label' | 'date' | 'dataset' | 'visualization' | 'dashboard' | 'document', required: Source object type (e.g., 'dashboard', 'visualization', 'metric').
    - `targetType` 'attribute' | 'metric' | 'fact' | 'label' | 'date' | 'dataset' | 'visualization' | 'dashboard' | 'document', required: Target object type (e.g., 'visualization', 'metric', 'attribute').
  - `deepSearch` boolean: Turn on deep search. If true, content of complex objects will be searched as well, e.g. metrics in visualizations.
  - `enableHybridSearch` boolean: If true, enables hybrid search combining vector similarity and keyword matching. This can improve search results by considering both semantic similarity and exact keyword matches.
  - `excludeTags` string[]: Exclude objects that contain any of the specified tags. This parameter only affects the search results. Objects with excluded tags are completely hidden from the results.
  - `includeHidden` boolean: If true, includes hidden objects in search results. If false (default), excludes objects where isHidden=true.
  - `includeTags` string[]: Include only objects that contain at least one of the specified tags (OR logic). This parameter only affects the search results. If an object has multiple tags, it will be included as long as it matches at least one tag from this parameter.
  - `limit` integer: Maximum number of results to return. There is a hard limit and the actual number of returned results may be lower than what is requested. This can happen when post-search filters are applied (e.g., reranker threshold filtering or allowedRelationshipTypes filtering), which may exclude some results after the initial search.
  - `objectTypes` string[]: Object type to search for.
  - `question` string, required: Keyword/sentence is input for search.
  - `relevantScoreThreshold` number: Score, above which we return found objects. Below this score objects are not relevant.
  - `titleToDescriptorRatio` number: Temporary for experiments. Ratio of title score to descriptor score.

## Response `200`

Successful Response

- SearchResult
  - `error` ErrorInfo
    - `reason` string, required: Stable machine-readable error code. Switch on this for localized client messages.
    - `statusCode` integer, required: HTTP-like semantic status (e.g. 503 when the workspace is still syncing).
  - `reasoning` string, required: DEPRECATED: Use top-level reasoning.steps instead. If something is not working properly this field will contain explanation.
  - `relationships` SearchRelationshipObject[], required: Relationships between the results.
    - `sourceObjectId` string, required: Source object ID.
    - `sourceObjectTitle` string, required: Source object title.
    - `sourceObjectType` string, required: Source object type, e.g. dashboard.
    - `sourceWorkspaceId` string, required: Source workspace ID. If relationship is dashboard->visualization, this is the workspace where the dashboard is located.
    - `targetObjectId` string, required: Target object ID.
    - `targetObjectTitle` string, required: Target object title.
    - `targetObjectType` string, required: Target object type, e.g. visualization.
    - `targetWorkspaceId` string, required: Target workspace ID. If relationship is dashboard->visualization, this is the workspace where the visualization is located.
  - `results` SearchResultObject[], required: Search results.
    - `certification` CertificationInfo: Certification state of the object. Who certified and when are never exposed here.
      - `certificationMessage` string: Optional message describing the certification.
      - `status` string, required: Certification status, e.g. CERTIFIED.
    - `createdAt` string: Timestamp when object was created.
    - `description` string: Object description.
    - `id` string, required: Object ID.
    - `isHidden` boolean: If true, this object is hidden from AI search results by default.
    - `modifiedAt` string: Timestamp when object was last modified.
    - `score` number: Result score calculated by a similarity search algorithm (cosine_distance).
    - `scoreDescriptor` number: Result score for descriptor containing(now) description and tags.
    - `scoreExactMatch` integer: Result score for exact match(id/title). 1/1000. Other scores are multiplied by this.
    - `scoreTitle` number: Result score for object title.
    - `tags` string[]: List of tags assigned to the object.
    - `title` string, required: Object title.
    - `type` string, required: Object type, e.g. dashboard.
    - `visualizationUrl` string: If the object is visualization, this field defines the type of visualization.
    - `workspaceId` string, required: Workspace ID.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gooddata/apis/gooddata-cn-oapi-all-api.md) - [All operations](https://skmtc.dev/gooddata/apis/gooddata-cn-oapi-all-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gooddata/apis/gooddata-cn-oapi-all-api/revisions/c728ef303bfb?raw)