> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/jira-api.md).

# Jira issues (JQL)

Pull Jira issues using JQL filters into Google Sheets, Excel, or BigQuery with Coupler.io for flexible issue tracking and analysis.

Jira is a powerful project management platform used by teams to track issues, bugs, and tasks. With Coupler.io, you can pull Jira issues using JQL (Jira Query Language) filters to analyze, report on, and combine issue data with other sources.

## Why connect Jira to Coupler.io?

* **Flexible filtering** — Use JQL to pull exactly the issues you need, whether it's a simple filter or a complex query
* **Custom analysis** — Export issue data to Google Sheets, Excel, BigQuery, or AI destinations like Claude or ChatGPT for advanced analysis
* **Combine data sources** — Join Jira issues with data from other tools (e.g., append time-tracking data, join with customer feedback)
* **Automated reporting** — Build dashboards in Looker Studio or other BI tools using fresh Jira data

## Prerequisites

* A Jira Cloud account with at least read access to the projects you want to query
* Permission to create API tokens (if using API key authentication)
* A destination to send your data (Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination)

## Quick start

{% hint style="success" %}
If you're new to JQL, start with a simple query like `project = "YOUR_PROJECT_KEY"` to pull all issues from a project. You can always refine the query later.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Click "+ New data flow"** on the Coupler.io dashboard and search for "Jira issues (JQL)".
{% endstep %}

{% step %}
**Click "Authorize"** in the Jira authentication modal. You'll be redirected to Jira Cloud to sign in. Coupler.io will request permission to read issues from your Jira account.
{% endstep %}

{% step %}
**Select your Jira Cloud site** from the "Site" dropdown. If you manage multiple Jira instances, choose the one containing the issues you want to export.
{% endstep %}

{% step %}
**Enter your JQL query** in the "JQL" field. For example:

* `project = "PROJ" AND status = "In Progress"` — all in-progress issues in a project
* `assignee = currentUser()` — issues assigned to you
* `created >= -7d AND type = "Bug"` — bugs created in the last 7 days

Leave this field empty to pull all issues accessible to you.
{% endstep %}

{% step %}
**Choose an export format**:

* **Jira CSV export** — Data in Jira's standard format (simpler, familiar layout)
* **Detailed data** — All metadata including IDs, URLs, and custom fields as separate columns (better for advanced analysis)
  {% endstep %}

{% step %}
**(Optional) Select specific columns** in the "Columns" field. Enter each column name on a new line. If left empty, all navigable fields will be exported. To find column names, export a sample to a spreadsheet first and copy the headers.
{% endstep %}

{% step %}
**Choose a destination** for your data (Google Sheets, Excel, BigQuery, Looker Studio, Claude, ChatGPT, or another supported platform).
{% endstep %}

{% step %}
**Click "Run now"** to execute the data flow. After a successful manual run, you'll be able to schedule future refreshes.
{% endstep %}
{% endstepper %}

## Jira issues (JQL) data overview

When you pull Jira issues via JQL, you get a flat list of issues with columns representing different fields. The data structure depends on your export format choice.

## Export formats

| Format              | Description                                         | Best for                                                        |
| ------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
| **Jira CSV export** | Standard Jira format with commonly-used fields      | Reports, dashboards, familiar layout                            |
| **Detailed data**   | All metadata including IDs, URLs, and custom fields | Advanced analysis, data warehousing, joining with other sources |

## Common fields

#### Standard fields

| Field       | Description                               | Type      |
| ----------- | ----------------------------------------- | --------- |
| Issue key   | Unique issue identifier (e.g., PROJ-123)  | Text      |
| Summary     | Issue title                               | Text      |
| Description | Full issue description                    | Text      |
| Status      | Current workflow status                   | Text      |
| Assignee    | User assigned to the issue                | Text      |
| Reporter    | User who created the issue                | Text      |
| Priority    | Priority level (e.g., High, Medium, Low)  | Text      |
| Type        | Issue type (Bug, Task, Story, Epic, etc.) | Text      |
| Created     | Issue creation timestamp                  | Date/Time |
| Updated     | Last update timestamp                     | Date/Time |
| Due date    | Target completion date                    | Date      |

#### Sprint & board fields (Scrum/Kanban)

| Field        | Description                      | Type   |
| ------------ | -------------------------------- | ------ |
| Sprint       | Sprint the issue belongs to      | Text   |
| Epic         | Parent epic link                 | Text   |
| Story points | Estimated effort in story points | Number |
| Components   | Technical components involved    | Text   |

#### Custom fields

Any custom fields configured in your Jira instance (e.g., "Client Name", "Environment", "Root Cause") will be included in the detailed data export.

## Common metric combinations

Here are useful analysis patterns you can build with Jira data:

* **Issues by status over time** — Track workflow progress by counting issues per status
* **Burndown analysis** — Combine story points with sprint dates for velocity tracking
* **Bug lifecycle** — Calculate average time from creation to resolution by comparing created and updated dates
* **Workload by assignee** — Count or sum story points grouped by assignee
* **Issue resolution rate** — Calculate percentage of issues moved to "Done" in a time period

## Use cases by role

{% tabs %}
{% tab title="Engineering managers" %}
Monitor sprint progress, identify bottlenecks, and track team velocity. Pull issues grouped by sprint and status to build burndown charts. Use story points to forecast capacity and plan upcoming sprints.
{% endtab %}

{% tab title="Product managers" %}
Track feature requests, prioritize backlog items, and monitor issue resolution times. Export issues by type and priority to understand feature delivery rates and bug response times.
{% endtab %}

{% tab title="Operations/support teams" %}
Monitor bug reports and support tickets. Filter for critical issues and track resolution times. Analyze incident trends by priority and component to identify areas needing attention.
{% endtab %}

{% tab title="Data analysts" %}
Combine Jira data with other sources (CRM, time tracking, surveys) for deeper insights. Use detailed data export to preserve metadata for complex joins and aggregations in BigQuery or your data warehouse.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **JQL macros supported** — Coupler.io supports Jira macros like `currentUser()`, `now()`, and relative date ranges (e.g., `-7d`, `-30d`) in JQL queries
* **Custom fields** — Custom fields appear in the detailed data export; column names match your Jira configuration
* **Permissions** — You can only pull issues you have permission to view in Jira
* **Rate limits** — Jira Cloud has API rate limits; large exports may take longer but will respect throttling
* **Field differences** — Different issue types may have different available fields; not all columns will have values for every issue

## Jira issues (JQL) common issues

### Connection issues

<details>

<summary>"Authorization failed" or "Invalid Jira site" error</summary>

This usually means the OAuth token expired or the Jira instance is no longer accessible. Try re-authorizing by clicking the "Authorize" button again. Make sure you're signing into the correct Jira Cloud instance that contains your issues.

</details>

<details>

<summary>"No Jira Cloud sites found" in the site dropdown</summary>

Your account may not be an admin or member of any Jira Cloud instances, or the OAuth token doesn't have the required permissions. Check that:

* You're signed into the correct Jira account
* Your account has access to at least one Jira Cloud site
* You have permission to create API tokens in your Jira instance

If you just created a Jira Cloud instance, wait a few minutes and re-authorize.

</details>

### Missing data

<details>

<summary>Data flow pulls 0 issues or fewer than expected</summary>

Check your JQL query. Common reasons for missing data:

* Query syntax error (missing quotes, incorrect operators)
* Query filters to projects you don't have access to
* Issues don't match the filter criteria

Test your JQL directly in Jira's issue navigator first. Try a simpler query like `project = "YOUR_PROJECT"` to verify it returns results. If it works in Jira but not in Coupler.io, check the exact project key spelling.

</details>

<details>

<summary>Custom fields are missing or showing blank values</summary>

Custom fields only appear in the **Detailed data** export format. If you're using "Jira CSV export", switch to "Detailed data" to see custom fields.

Some custom fields may be empty for specific issues if they haven't been set. This is normal and expected.

</details>

<details>

<summary>Assignee, Reporter, or other user fields show IDs instead of names</summary>

This occurs with the **Detailed data** export format, which preserves raw API values (user account IDs). Switch to **Jira CSV export** for human-readable names, or use a transformation in your destination to map IDs to names if needed.

</details>

### Permission errors

<details>

<summary>"Permission denied" or "You don't have permission to view this issue"</summary>

Your Jira account doesn't have permission to access some of the issues in your query. This can happen if:

* You're querying a project you're not a member of
* Issues are in a restricted board or component
* Your account's permission level changed

Modify your JQL to query only projects or issues you have access to. Ask your Jira admin if you need permission to additional projects.

</details>

### Data discrepancies

<details>

<summary>Issue count differs between Jira and my export</summary>

Check the following:

* Your JQL query may not match what you expect; test it in Jira's issue navigator
* Some issues may have been deleted or moved outside your query scope since the last run
* Large exports may be paginated; ensure your data flow completed successfully

Run the data flow again and compare the row count to your Jira search results.

</details>

<details>

<summary>Updated date is older than expected</summary>

The "Updated" field reflects the last change to any field, not just status changes. Minor updates like adding a comment or modifying a custom field will update this timestamp. If you need the last status change, you may need to manually track this or use Jira's activity history.

</details>

### Rate limits

<details>

<summary>Data flow is slow or times out on large exports</summary>

Jira Cloud API has rate limits (typically 300 requests per 10 seconds). Large issue exports respect these limits but may take longer. To improve performance:

* Narrow your JQL query to fewer issues (e.g., add a date range: `created >= -30d`)
* Export only the columns you need instead of all fields
* Run the data flow during off-peak hours

Coupler.io will automatically handle rate limit backoff; your export will succeed but may take longer.

</details>

## Jira issues (JQL) FAQ

<details>

<summary>What is JQL and how do I write a query?</summary>

JQL (Jira Query Language) is Jira's search syntax. It lets you filter issues by any field. Common examples:

* `project = "PROJ"` — Issues in a specific project
* `status = "Done"` — Completed issues
* `assignee = currentUser()` — Issues assigned to you
* `created >= -7d` — Issues created in the last 7 days
* `priority = "High" AND type = "Bug"` — High-priority bugs

See Atlassian's [JQL tutorial](https://www.atlassian.com/blog/jira-software/jql-the-most-flexible-way-to-search-jira-14) for detailed documentation.

</details>

<details>

<summary>Can I use macros in my JQL query?</summary>

Yes! Coupler.io supports Jira macros like `currentUser()`, `now()`, and relative dates (`-7d`, `-30d`, `-1h`). This is useful for queries that need to be dynamic:

* `assignee = currentUser()` — Always pulls issues for the logged-in user
* `updated >= -1d` — Issues updated in the last day
* `created >= startOfMonth()` — Issues created since the first of the month

{% hint style="info" %}
Learn more about [macros in Coupler.io](https://docs.coupler.io/functionality/macros-in-data-flows).
{% endhint %}

</details>

<details>

<summary>What's the difference between "Jira CSV export" and "Detailed data" formats?</summary>

**Jira CSV export** uses Jira's standard export format with commonly-used fields (Summary, Status, Assignee, etc.). It's simpler and more readable.

**Detailed data** exports all metadata including issue IDs, URLs, and raw API values. It's better if you're joining Jira data with other sources or doing advanced analysis in BigQuery. User fields (Assignee, Reporter) will show account IDs instead of names in this format.

Choose based on your destination: use CSV export for Google Sheets dashboards, detailed data for warehouse analysis.

</details>

<details>

<summary>Can I pull data from multiple Jira projects in one data flow?</summary>

Yes! Use JQL to query multiple projects: `project in ("PROJ1", "PROJ2", "PROJ3")`. This pulls all issues from all three projects into a single list. You can then filter or group them in your destination (Google Sheets, BigQuery, etc.).

If you need to keep projects separate or apply different transformations to each, create multiple data flows—one per project.

</details>

<details>

<summary>How do I export only specific columns?</summary>

Enter column names (one per line) in the "Columns" field. To find exact column names, export a sample of your data first and copy the header row.

If you leave "Columns" blank, all navigable fields will be exported. Limiting columns can speed up your data flow, especially if your Jira instance has many custom fields.

</details>

<details>

<summary>Can I join Jira data with other sources?</summary>

Yes! Coupler.io supports **Join**, **Append**, and **Aggregate** transformations. For example:

* **Join** Jira issues with your time-tracking system on issue key
* **Append** issues from multiple Jira projects into one dataset
* **Aggregate** story points by assignee to see workload distribution

Use the "Detailed data" export format to preserve IDs and metadata for cleaner joins.

{% hint style="info" %}
See the [data overview](#jira-issues-jql-data-overview) for common metric combinations and analysis patterns.
{% endhint %}

</details>

<details>

<summary>Can I send Jira data to an AI destination like Claude or ChatGPT?</summary>

Yes! Coupler.io supports AI destinations including Claude, ChatGPT, Cursor, Gemini, Perplexity, and OpenClaw. You can export Jira issues directly to these platforms for analysis, summarization, or other AI-powered tasks. Select your preferred AI destination when setting up the data flow.

</details>

<details>

<summary>Why is my data flow running slowly on large exports?</summary>

Jira Cloud API has rate limits (typically 300 requests per 10 seconds). Large exports respect these limits but may take longer. To improve performance:

* Narrow your JQL query with date ranges or project filters
* Export only the columns you need
* Avoid overly broad queries like `type != Epic`

Coupler.io handles rate limiting automatically; your export will succeed but may take longer. For very large datasets, consider running exports during off-peak hours.

{% hint style="info" %}
See [best practices](https://docs.coupler.io/sources/category/project-management/jira-api/best-practices.md) for optimization tips.
{% endhint %}

</details>

<details>

<summary>What happens if a Jira issue is deleted after I export it?</summary>

Deleted issues won't appear in future exports. If you need to track historical issue data, archive your export to a separate sheet or data warehouse before deleting issues in Jira.

</details>

<details>

<summary>Can I export issue history or change logs?</summary>

The current export captures the current state of each issue (status, assignee, etc.). It does not include the full change history or activity log. If you need historical data, export a snapshot regularly and compare versions, or use Jira's built-in audit log and activity history.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/project-management/jira-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
