---
title: "Jira Search & Fields"
description: "Search issues with JQL, explore fields and field options"
---

### Search Issues

Search Jira issues using JQL (Jira Query Language).

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `jql` | `string` | Yes | JQL query string (Jira Query Language). Examples: - Find Epics: "issuetype = Epic AND project = PROJ" - Find issues in Epic: "parent = PROJ-123" - Find by status: "status = 'In Progress' AND project = PROJ" - Find by assignee: "assignee = currentUser()" - Find recently updated: "updated >= -7d AND project = PROJ" - Find by label: "labels = frontend AND project = PROJ" - Find by priority: "priority = High AND project = PROJ" |
| `fields` | `string` | No | (Optional) Comma-separated fields to return in the results. Use '*all' for all fields, or specify individual fields like 'summary,status,assignee,priority' |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
| `projects_filter` | `string` | No | (Optional) Comma-separated list of project keys to filter results by. Overrides the environment variable JIRA_PROJECTS_FILTER if provided. |
| `expand` | `string` | No | (Optional) fields to expand. Examples: 'renderedFields', 'transitions', 'changelog' |
| `page_token` | `string` | No | Pagination token from a previous search result. Cloud only — Server/DC uses `start_at` for pagination. |
**Example:**

```json
{"jql": "project = PROJ AND status = 'In Progress' ORDER BY updated DESC", "limit": 20}
```

<Tip>
Always use `ORDER BY` for deterministic results. Use `fields` parameter to limit returned data for faster queries.
</Tip>


<Warning>
Some JQL functions (e.g., `issueHistory()`) are Cloud-only.
</Warning>

<Tip>
Cloud supports cursor-based pagination via `page_token` for deterministic results across large datasets. The token is returned in the `next_page_token` field of search results.
</Tip>


---

### Search Fields

Search Jira fields by keyword with fuzzy match.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `keyword` | `string` | No | Keyword for fuzzy search. If left empty, lists the first 'limit' available fields in their default order. |
| `limit` | `integer` | No | Maximum number of results |
| `refresh` | `boolean` | No | Whether to force refresh the field list |
**Example:**

```json
{"keyword": "story points", "issue_type": "Story", "project_key": "PROJ"}
```

<Tip>
Use this to discover custom field IDs before using them in `jira_create_issue` or `jira_update_issue`.
</Tip>


---

### Get Field Options

Get allowed option values for a custom field.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `field_id` | `string` | Yes | Custom field ID (e.g., 'customfield_10001'). Use jira_search_fields to find field IDs. |
| `context_id` | `string` | No | Field context ID (Cloud only). If omitted, auto-resolves to the global context. |
| `project_key` | `string` | No | Project key (required for Server/DC). Example: 'PROJ' |
| `issue_type` | `string` | No | Issue type name (required for Server/DC). Example: 'Bug' |
| `contains` | `string` | No | Case-insensitive substring filter on option values. Also matches child values in cascading selects. |
| `return_limit` | `integer` | No | Maximum number of results to return (applied after filtering). |
| `values_only` | `boolean` | No | If true, return only value strings in a compact JSON format instead of full option objects. |

**Example:**

```json
{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}
```

<Tip>
Use `contains` to filter large option lists (e.g., hundreds of values). Combine with `values_only: true` for a compact response.
</Tip>

---
