> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Search Tree > Search across your teamspace's indexed knowledge and return results as a hierarchical context tree. Results are grouped by source (datasets, files, pages) with navigation items for quick access. Supports pagination via cursor-based `next` parameter. This endpoint is the foundation for the AI Search endpoint — use this when you need structured results without AI summarization. ## OpenAPI ````yaml get /search/tree openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /search/tree: get: tags: - Search summary: Search Tree description: > Search across your teamspace's indexed knowledge and return results as a hierarchical context tree. Results are grouped by source (datasets, files, pages) with navigation items for quick access. Supports pagination via cursor-based `next` parameter. This endpoint is the foundation for the AI Search endpoint — use this when you need structured results without AI summarization. operationId: searchTree parameters: - name: query description: The natural language search query. in: query required: true schema: type: string - name: record_types description: >- Filter results by record type in the vector database. When omitted, all record types are searched. in: query required: false schema: type: array items: $ref: '#/components/schemas/SearchRecordType' - name: display_type description: >- Filter results to one display type (dataset, document, image, or channel). Applied before pagination, so pages cover the full filtered result pool. When omitted, all display types are returned. Honored when paginated search is enabled for the teamspace (Gen Search phase 3). in: query required: false schema: $ref: '#/components/schemas/SearchDisplayType' - $ref: '#/components/parameters/next' - $ref: '#/components/parameters/limit' responses: '200': description: >- A tree of search results grouped by source, with navigation items and pagination. content: application/json: schema: $ref: '#/components/schemas/SearchTreeResult' headers: X-Daily-Credit-Cap-Remaining: $ref: '#/components/headers/DailyCreditCapRemaining' X-Monthly-Credit-Cap-Remaining: $ref: '#/components/headers/MonthlyCreditCapRemaining' '402': description: >- Credit limit exceeded. Either the organization does not have enough credits to perform this search, or it has reached the monthly credit cap set in Control Tower. Check your billing status, or wait for the cap to reset. headers: X-Daily-Credit-Cap-Remaining: $ref: '#/components/headers/DailyCreditCapRemaining' X-Monthly-Credit-Cap-Remaining: $ref: '#/components/headers/MonthlyCreditCapRemaining' '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: SearchRecordType: type: string description: The record type in the vector database. enum: - rows - tables - files - pages - cells SearchDisplayType: type: string description: >- Product-facing grouping of one result card, aligned with the result tabs in the Datagrid web app. Derived from the card's structure and media type: tables and records are `dataset`, files with an `image/*` media type are `image`, other files and pages are `document`, and channels are `channel`. enum: - dataset - document - image - channel SearchTreeResult: type: object description: >- Hierarchical search results grouped by source (datasets, files, pages) with navigation items. required: - object - query - data - nav_items - has_more - credits properties: object: type: string enum: - search_tree description: The object type, always `search_tree`. query: type: string description: The original search query. data: type: array items: type: object description: >- Tree nodes representing search results grouped by source. Each node contains the matched content, metadata, score, and child nodes for hierarchical display. nav_items: type: array items: type: object description: >- Navigation items providing quick links to the datasets, tables, and files that matched the query. Each item includes a name, emoji, URL, and type. has_more: type: boolean description: >- Whether more results are available beyond this page. Use the `next` cursor to fetch additional results. next: type: string nullable: true description: >- Pagination cursor (numeric offset as string). Pass this value as the `next` query parameter to `/search/tree` to fetch the next page. total_count: type: integer nullable: true description: >- Total number of grouped results in the ranked result pool across all pages (capped by the retrieval pool limit). Only present when paginated search is enabled for the teamspace (Gen Search phase 3). counts_by_display_type: nullable: true description: >- Number of results per display type across the entire result pool, independent of the current page or any filter. Only present when paginated search is enabled for the teamspace (Gen Search phase 3). allOf: - $ref: '#/components/schemas/SearchCountsByDisplayType' display_items: type: array nullable: true items: $ref: '#/components/schemas/SearchDisplayItem' description: >- Canonical ordered result cards for this page — one item per result, in ranked order with pinned dataset/channel supplements first. Render these directly instead of traversing `data`. Only present when paginated search is enabled for the teamspace (Gen Search phase 3). credits: nullable: true description: >- Credit consumption for this search. When present, `consumed` reflects the actual variable cost of the retrieval work performed for this request. `null` when the billing write fails or the request is aborted before billing completes. allOf: - $ref: '#/components/schemas/OperationCredits' RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. SearchCountsByDisplayType: type: object description: Result counts per display type across the entire result pool. required: - datasets - documents - images - channels properties: datasets: type: integer description: >- Number of dataset results: tables, data records, and name-matched datasets. documents: type: integer description: >- Number of document results: non-image files and standalone pages (multiple matched pages of one file count as a single file). images: type: integer description: 'Number of image results: files with an `image/*` media type.' channels: type: integer description: Number of name-matched channel results. SearchDisplayItem: type: object description: >- One search result card with no structural children. Items arrive in ranked page order; each corresponds to exactly one rendered result. required: - object - id - kind - display_type - table_id properties: object: type: string enum: - search_display_item description: The object type, always `search_display_item`. id: type: string description: >- Stable identifier of the result (document id for retrieval results, entity id for dataset/channel supplements). kind: type: string enum: - record - file - page - dataset - channel description: >- The kind of result card: a data record, a file, a single file page, a dataset, or a channel. display_type: description: >- Product-facing grouping of this card, aligned with the result tabs in the Datagrid web app. allOf: - $ref: '#/components/schemas/SearchDisplayType' title: type: string description: Card title. body: type: string description: Card body text (matched content snippet). score: type: number description: Relevance score of the result, between 0 and 1. created_at: type: string description: When the underlying item was created. updated_at: type: string description: When the underlying item was last updated. url: type: string description: >- Resolved navigation target: a trusted source deep link when available, otherwise the dataset URL in the Datagrid web app. dataset_name: type: string description: Name of the dataset this result belongs to. table_name: type: string description: Name of the table this result belongs to. table_id: type: string description: Identifier of the table this result belongs to. table_fingerprint: type: string description: Fingerprint of the table, used to build dataset URLs. navigation_item_id: type: string description: Identifier of the navigation item for the dataset or channel. emoji: type: string description: Emoji icon of the dataset or channel. file_uri: type: string description: >- Datagrid file URI for file/page media, used to resolve thumbnails and viewers. media_type: type: string description: Media type of the file (e.g. `application/pdf`, `image/png`). data_lake_item_id: type: string description: Identifier of the data-lake item backing the file. page_number: type: integer description: 1-based page number within the source document, for `page` items. page_url: type: string description: Datagrid file URI scoped to this page, for `page` items. total_pages: type: integer description: Total number of pages in the source document. parent_record: description: >- The record (row) this file or page is attached to, when it belongs to one — for example the RFI a photo was uploaded with. Present only for `file` and `page` items. allOf: - $ref: '#/components/schemas/SearchParentRecord' channel_data: description: Channel details. Present only for `channel` items. allOf: - $ref: '#/components/schemas/SearchDisplayItemChannelData' OperationCredits: type: object required: - consumed properties: consumed: type: number description: The number of credits consumed by the operation. SearchParentRecord: type: object description: The record (row) a file or page search result is attached to. required: - id properties: id: type: string description: Document identifier of the record. title: type: string description: Record title. body: type: string description: Record summary text. SearchDisplayItemChannelData: type: object description: Channel membership and visibility details for channel search results. required: - channel_type - is_private - is_joined - participant_count - people_count - agent_count properties: channel_type: type: string description: One of `channel`, `directMessage`, or `chats`. is_private: type: boolean description: Whether the channel is private. is_joined: type: boolean description: Whether the requesting user is a member of this channel. participant_count: type: integer description: Total number of members (people + agents). people_count: type: integer description: Number of human members. agent_count: type: integer description: Number of AI/agent members. parameters: next: name: next in: query schema: type: string required: false description: >- A cursor to use in pagination to continue a query from the previous request. This is automatically added when the request has more results to fetch. limit: name: limit in: query schema: type: integer default: 50 minimum: 1 maximum: 100 required: false description: The limit on the number of objects to return, ranging between 1 and 100. headers: DailyCreditCapRemaining: description: >- Credits left before the account's daily credit cap (set in Control Tower) is reached, rounded up. `0` means the cap has been reached; the daily cap does not block requests. Present only when a daily cap is configured. schema: type: integer example: 600 MonthlyCreditCapRemaining: description: >- Credits left before the account's monthly credit cap (set in Control Tower) is reached, rounded up. At `0`, credit-consuming requests return `402` until the next calendar month. Present only when a monthly cap is configured. schema: type: integer example: 15000 securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.