---
title: "Run a global search"
description: "Searches Mindtickle learning site content across entities and returns results ranked by semantic relevance."
contentType: "api-reference"
url: "https://developer.mindtickle.com/docs/search/global-search/run-a-global-search/"
---

## Prerequisites

1. [Authentication and setup](/docs/getting-started/authentication-and-setup/): A valid access token.

## Endpoint

```http
POST /v1/global-search
```

Base URL: the API3 host for your region, not the standard REST host. See [Base URLs](/docs/getting-started/authentication-and-setup/#base-urls).

Headers: `Authorization: Bearer ACCESS_TOKEN`, `Content-Type: application/json`. Both are required.

## Request

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | string | Required | User initiating the request. |
| `search_text` | string | Required | Search term entered by the user. |
| `entities` | array | Required | List of entities to search, with optional filters. Each entity object can include the fields below. |
| `entities.entity_type` | string | Not specified | Type of entity to search, for example `MODULES` or `COURSES`. |
| `entities.module_filters` | object | Optional | Module filters that refine search results, for example `module_types` and `module_tags`. |
| `entities.rank_entity_docs` | boolean | Optional | Determines whether the entity documents are included for this entity type. See Notes. |
| `pagination` | object | Optional | Pagination options. See [Pagination and sorting](#notes) before requesting subsequent pages. |
| `pagination.size` | integer | Not specified | Number of results to return, up to 50. |

### Request example

```json
{
  "username": "john.doe@example.com",
  "search_text": "sales onboarding",
  "entities": [
    {
      "entity_type": "MODULES",
      "module_filters": {
        "module_types": ["COURSE", "MISSION"],
        "module_tags": ["onboarding", "sales"]
      },
      "rank_entity_docs": true
    }
  ],
  "pagination": {
    "size": 25
  }
}
```

## Response

| Field | Type | Description |
| --- | --- | --- |
| `entities` | array | Array of matched entities with metadata. |
| `entity_total_count` | array | Count of matched entities per type. |
| `page_response` | object | Pagination data and next cursor if available. |

### Response example

```json
{
  "entities": [
    {
      "entity_type": "MODULES",
      "entity_id": "1234567890123456101",
      "entity_name": "Sales Onboarding 101",
      "type": "COURSE",
      "media_type": "UNDEFINED_CONTENT_TYPE",
      "score": 0.987
    }
  ],
  "entity_total_count": [
    {
      "entity_type": "MODULES",
      "count": 10
    }
  ],
  "page_response": {
    "total_hits": 10,
    "next_cursor": "cursor_abc123"
  }
}
```

## Errors

| Status | Error | Message | Reason |
| --- | --- | --- | --- |
| `400` | `INVALID_REQUEST` | Missing required parameter | Required field missing or invalid. |
| `401` | `UNAUTHORIZED` | Invalid or expired token | Token missing, invalid, or expired. |
| `429` | `RATE_LIMIT_EXCEEDED` | Too many requests | Exceeded API rate limits. |
| `500` | `INTERNAL_ERROR` | Internal server error | Unexpected server-side failure. |

## Notes

- **Ranking:** When `rank_entity_docs` is `true`, matching documents are included for ranking and pagination. When it is `false`, only the count is included, and the documents are excluded from the ranked results.
- **Rate limits:** 600 requests per minute and 3,000 requests per hour.
- **Limits:** Maximum 50 results per page.
- **Pagination and sorting:** Use `pagination.size` to limit results. Before implementing subsequent pages or custom sorting, confirm the continuation request field and sorting parameters with [Mindtickle Support](mailto:support@mindtickle.com). Do not assume that the response field `page_response.next_cursor` is also a request field.
- **Entities:** For what each entity type searches, see [Searchable entities](/docs/search/global-search/#searchable-entities).