0
# Search
1

2
Search for messages, files, and content across the Slack workspace with flexible query options. The Search API provides powerful search capabilities similar to Slack's built-in search functionality.
3

4
## Capabilities
5

6
### Search All
7

8
Search for both messages and files matching a query across the workspace.
9

10
```typescript { .api }
11
/**
12
 * Search for messages and files matching a query
13
 * @param options - Search parameters with query and options
14
 * @returns Promise resolving to combined search results
15
 */
16
search.all(options: SearchAllArguments): Promise<SearchAllResponse>;
17

18
interface SearchAllArguments extends TokenOverridable, TraditionalPagingEnabled, Searchable {}
19

20
interface Searchable extends OptionalTeamAssignable, SortDir {
21
  /** Search query string */
22
  query: string;
23
  /** Enable query highlight markers (default: false) */
24
  highlight?: boolean;
25
  /** Sort results by 'score' or 'timestamp' (default: 'score') */
26
  sort?: 'score' | 'timestamp';
27
}
28

29
interface SearchAllResponse extends WebAPICallResult {
30
  /** Combined search results */
31
  messages?: SearchMessageResults;
32
  files?: SearchFileResults;
33
  /** Search query that was executed */
34
  query?: string;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { WebClient } from "@slack/web-api";
42

43
const web = new WebClient(process.env.SLACK_BOT_TOKEN);
44

45
// Search for messages and files containing "project update"
46
const results = await web.search.all({
47
  query: "project update",
48
  sort: "timestamp",
49
  highlight: true
50
});
51

52
// Search with pagination
53
const page1 = await web.search.all({
54
  query: "bug report",
55
  count: 20,
56
  page: 1
57
});
58
```
59

60
### Search Files
61

62
Search specifically for files matching a query.
63

64
```typescript { .api }
65
/**
66
 * Search for files matching a query  
67
 * @param options - Search parameters with query and options
68
 * @returns Promise resolving to file search results
69
 */
70
search.files(options: SearchFilesArguments): Promise<SearchFilesResponse>;
71

72
interface SearchFilesArguments extends TokenOverridable, TraditionalPagingEnabled, Searchable {}
73

74
interface SearchFilesResponse extends WebAPICallResult {
75
  /** File search results */
76
  files?: SearchFileResults;
77
  /** Search query that was executed */
78
  query?: string;
79
}
80

81
interface SearchFileResults {
82
  /** Total number of files found */
83
  total?: number;
84
  /** Pagination information */
85
  paging?: SearchPaging;
86
  /** Array of matching files */
87
  matches?: FileMatch[];
88
}
89

90
interface FileMatch {
91
  /** File object */
92
  file?: File;
93
  /** Search score */
94
  score?: number;
95
  /** Highlighted preview text */
96
  preview?: string;
97
  /** Highlighted preview (HTML) */
98
  preview_highlight?: string;
99
}
100
```
101

102
### Search Messages
103

104
Search specifically for messages matching a query.
105

106
```typescript { .api }
107
/**
108
 * Search for messages matching a query
109
 * @param options - Search parameters with query and options  
110
 * @returns Promise resolving to message search results
111
 */
112
search.messages(options: SearchMessagesArguments): Promise<SearchMessagesResponse>;
113

114
interface SearchMessagesArguments extends TokenOverridable, TraditionalPagingEnabled, Searchable {}
115

116
interface SearchMessagesResponse extends WebAPICallResult {
117
  /** Message search results */
118
  messages?: SearchMessageResults;
119
  /** Search query that was executed */  
120
  query?: string;
121
}
122

123
interface SearchMessageResults {
124
  /** Total number of messages found */
125
  total?: number;
126
  /** Pagination information */
127
  paging?: SearchPaging;
128
  /** Array of matching messages */
129
  matches?: MessageMatch[];
130
}
131

132
interface MessageMatch {
133
  /** Message object */
134
  message?: Message;
135
  /** Search score */
136
  score?: number; 
137
  /** Channel information */
138
  channel?: {
139
    id?: string;
140
    name?: string;
141
    is_channel?: boolean;
142
    is_group?: boolean;
143
    is_im?: boolean;
144
    is_mpim?: boolean;
145
  };
146
  /** Message type */
147
  type?: string;
148
  /** User who sent the message */
149
  user?: string;
150
  /** Username who sent the message */
151
  username?: string;
152
  /** Timestamp of the message */
153
  ts?: string;
154
  /** Message text with highlights */
155
  text?: string;
156
  /** Previous message context */
157
  previous?: MessageContext;
158
  /** Next message context */
159
  next?: MessageContext;
160
}
161

162
interface MessageContext {
163
  /** Context message user */
164
  user?: string;
165
  /** Context message username */
166
  username?: string;
167
  /** Context message text */
168
  text?: string;
169
  /** Context message timestamp */
170
  ts?: string;
171
  /** Context message type */
172
  type?: string;
173
}
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
// Search for messages containing specific keywords
180
const messageResults = await web.search.messages({
181
  query: "quarterly review",
182
  highlight: true,
183
  sort: "timestamp" 
184
});
185

186
// Search for files with specific types
187
const fileResults = await web.search.files({
188
  query: "filetype:pdf budget",
189
  count: 10
190
});
191

192
// Advanced query examples
193
const advancedSearch = await web.search.messages({
194
  query: "from:@john in:#general has:link after:2024-01-01",
195
  highlight: true
196
});
197
```
198

199
## Query Syntax
200

201
Slack search supports rich query syntax:
202

203
- **Basic text**: `project update`
204
- **From user**: `from:@username` or `from:me`
205
- **In channel**: `in:#channel` or `in:@username`
206
- **Date ranges**: `after:2024-01-01`, `before:2024-12-31`, `during:January`
207
- **File types**: `filetype:pdf`, `filetype:image`
208
- **Has attachments**: `has:link`, `has:attachment`
209
- **Exclude terms**: `-word` to exclude specific terms
210
- **Phrases**: `"exact phrase"` for exact matches
211

212
## Pagination
213

214
All search methods support traditional pagination:
215

216
```typescript
217
interface SearchPaging {
218
  /** Current page number */
219
  page?: number;
220
  /** Total number of pages */
221
  pages?: number;
222
  /** Items per page */
223
  count?: number;
224
  /** Total number of results */
225
  total?: number;
226
  /** Start index for current page */
227
  first?: number;
228
  /** End index for current page */  
229
  last?: number;
230
}
231

232
// Paginated search example
233
const searchPage = async (query: string, page: number) => {
234
  return await web.search.messages({
235
    query,
236
    page,
237
    count: 20
238
  });
239
};
240
```
241

242
## Core Types
243

244
```typescript { .api }
245
interface SortDir {
246
  /** Sort direction - 'asc' or 'desc' (default: 'desc') */
247
  sort_dir?: 'asc' | 'desc';
248
}
249

250
interface OptionalTeamAssignable {
251
  /** Team ID for Enterprise Grid workspaces */
252
  team_id?: string;
253
}
254

255
interface TraditionalPagingEnabled {
256
  /** Number of items to return per page */
257
  count?: number;
258
  /** Page number for pagination */
259
  page?: number;
260
}
261

262
interface TokenOverridable {
263
  /** Override the default token for this request */
264
  token?: string;
265
}
266
```