# Slack Search

> Search for messages in Slack workspaces using a user token with search:read scope.

Source: https://cotera.co/docs/reference/tools/individual-tools/slack-search

---

**Authentication Type:** API Key\
**Description:** Search for messages in Slack workspaces. Requires a Slack user token (starts with xoxp-) with search:read scope. This is separate from regular Slack messaging which uses bot tokens.

***

## Authentication

To authenticate, you'll need a Slack user token with the `search:read` scope:

1. Follow the [Slack User Token guide](https://docs.slack.dev/authentication/tokens/#user) to create a Slack app
2. Add the `search:read` scope to your app's user token scopes
3. Install the app to your workspace
4. Copy the user token (starts with `xoxp-`)

**Note:** This requires a user token, not a bot token. User tokens start with `xoxp-` while bot tokens start with `xoxb-`.

***

## Search

Search for messages across Slack workspace using user token.

### Search Messages

Search for messages in your Slack workspace. Use "in:#channel-name" or "in:channel\_id" to search specific channels (e.g., "hello in:#general" or "error in:C095Z8MEXFV"). Supports other operators like from:@username and date ranges. Requires a user token with search:read scope.

**Operation Type:** Mutation (Write)

**Parameters:**

* **query** `string` (required): Search query to find messages. To search in a specific channel, use "in:#channel-name" or "in:channel\_id". Example: "hello in:#general" or "error in:C095Z8MEXFV"
* **count** `number` (nullable): Number of messages to return (max 100, optional)
* **cursor** `string` (nullable): Pagination cursor for retrieving more results (optional)
* **highlight** `boolean` (nullable): Whether to highlight matching terms in results (optional)
* **page** `number` (nullable): Page number for results (max 100, optional)
* **sort** `string` (nullable): Sort order for results (timestamp or score, optional)
* **sortDir** `string` (nullable): Sort direction (asc or desc, optional)
* **teamId** `string` (nullable): Team ID for org-level tokens (optional)

**Returns:**

* **ok** `boolean`: Whether the search was successful
* **query** `string`: The search query that was executed
* **messages** `object`: Search results
  * **matches** `array of objects`: Array of matching messages
    * **channel** `object`: Channel information
      * **id** `string`: Channel ID
      * **name** `string`: Channel name
      * **isPrivate** `boolean`: Whether the channel is private
      * **isExtShared** `boolean`: Whether the channel is externally shared
      * **isMpim** `boolean`: Whether the channel is a multi-person IM
      * **isOrgShared** `boolean`: Whether the channel is org shared
      * **isPendingExtShared** `boolean`: Whether the channel has pending external sharing
      * **isShared** `boolean`: Whether the channel is shared
      * **pendingShared** `array of strings`: Pending shared connections
    * **iid** `string`: Internal message ID
    * **permalink** `string`: Permalink to the message
    * **team** `string`: Team ID
    * **text** `string`: Message text content
    * **ts** `string`: Message timestamp
    * **type** `string`: Message type
    * **user** `string`: User ID who sent the message
    * **username** `string`: Username who sent the message
  * **pagination** `object`: Pagination information
    * **first** `number`: First result number
    * **last** `number`: Last result number
    * **page** `number`: Current page number
    * **pageCount** `number`: Total number of pages
    * **perPage** `number`: Results per page
    * **totalCount** `number`: Total number of results
  * **paging** `object`: Paging information
    * **count** `number`: Number of results returned
    * **page** `number`: Current page
    * **pages** `number`: Total pages
    * **total** `number`: Total results
  * **total** `number`: Total number of matching messages

**Example Usage:**

```json
{
  "query": "project status in:#general from:@john",
  "count": 25,
  "sort": "timestamp",
  "sortDir": "desc",
  "highlight": true
}
```

***

## Common Use Cases

**Message Discovery:**

* Search for specific conversations across channels
* Find messages by keywords and phrases with channel filtering
* Locate information shared by specific team members

**Research and Analysis:**

* Find historical discussions about projects or decisions
* Search for error messages or technical discussions
* Discover patterns in team communication

**Audit and Compliance:**

* Search messages from specific users or time periods
* Find discussions about particular topics or projects
* Export message data for compliance or documentation purposes