> 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/best-practices.md). # Best Practices ## Recommended setup


Start with a simple JQL query	Before building complex queries, test with `project = "YOUR_PROJECT"` or `assignee = currentUser()` to understand the data. Once the data flow runs successfully, refine your query to add filters like status, date ranges, or custom fields.
Use "Detailed data" for analysis	If you're joining Jira data with other sources or building advanced reports, choose the "Detailed data" export format to preserve IDs and metadata. This makes it easier to join issues with other datasets later.
Select only the columns you need	If your Jira instance has many custom fields, explicitly list the columns you need in the "Columns" field. This reduces export size, speeds up the data flow, and makes your destination cleaner and easier to read.

## Data refresh and scheduling


Schedule daily refreshes for active projects	If your team moves issues frequently, schedule daily refreshes to keep your reporting sheets up to date. For slower-moving projects, weekly refreshes are usually sufficient.
Use date ranges in JQL to limit historical data	Instead of pulling all issues from the beginning of time, filter by creation date (e.g., `created >= -90d`) to keep exports manageable and faster. Archive old data separately if needed for historical analysis.

## Performance optimization


Filter by project or sprint first	Queries like `project = "PROJ"` are much faster than open searches. If using sprints, add `sprint = "Sprint Name"` to the query to significantly reduce the dataset.
Avoid overly broad JQL searches	Queries like `type != Epic` or `priority is not empty` scan your entire Jira instance. Add positive filters (e.g., `project in (PROJ1, PROJ2)`) to narrow scope and speed up execution.

## Common pitfalls {% columns %} {% column %} **Do** * Test your JQL in Jira's issue navigator before importing * Use project keys in uppercase (e.g., `project = "PROJ"`) * Update your JQL as your Jira structure changes * Pull only active issues regularly; archive historical data separately {% endcolumn %} {% column %} **Don't** * Share your Coupler.io data flow link with people who shouldn't see Jira data * Use complex JQL without testing it first in Jira * Export all custom fields if you only need a few; this slows down your flow * Rely on exact field order—field positions may shift if custom fields are added/removed in Jira {% endcolumn %} {% endcolumns %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coupler.io/sources/category/project-management/jira-api/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.