Knowi enables visualization, analysis, and reporting automation from your Jira project management data.

Connect your Jira Cloud instance to pull issues, projects, boards, sprints, and custom data into Knowi for analytics and dashboards - no manual exports needed.

Overview

Connect to your Jira Cloud instance using API token authentication. Knowi handles pagination and data extraction automatically.

Jira uses Basic authentication with your email and an API token. Knowi handles the encoding automatically - just enter your email:apiToken and you're set.

Prerequisites

You need two things to connect Jira to Knowi: your Jira domain and an API token.

Step 1: Find Your Jira Domain

Your Jira domain is the URL you use to access Jira in your browser. It looks like:

https://yourcompany.atlassian.net

The domain is just the yourcompany.atlassian.net part without https://.

How to find it:

1. Log in to Jira in your browser
2. Look at the address bar. It will show something like https://yourcompany.atlassian.net/jira/... . 
3. Your domain is yourcompany.atlassian.net
4. For Jira Server/Data Center, it may be a custom domain like jira.yourcompany.com

Example: If your Jira URL is https://knowi.atlassian.net/jira/software/projects/ENG/board/1, then your domain is knowi.atlassian.net.

Step 2: Generate a Jira API Token

1. Go to id.atlassian.com/manage-profile/security/api-tokens (or log in to id.atlassian.com and navigate to Security > API tokens).
2. Click Create API token.
3. Enter a label (e.g., "Knowi Integration") and click Create.
4. Copy the token immediately - Atlassian only shows it once.
5. In Knowi, enter the access token as email:apiToken. For example: jay@knowi.com:ATATT3xFfGF0UbQt8SwgBXXx...

Connecting

1. Log in to Knowi and navigate to Queries from the left sidebar.
2. Click New Datasource (the + icon), then search for Jira in the datasource selector.

3. Fill in the form:

   a. Datasource Name: A label for this connection (e.g., "Jira Cloud")

   b. Jira Domain: Your Jira Cloud domain - just the hostname, without https:// (e.g., mycompany.atlassian.net)

   c. Access Token: Enter your email:apiToken (e.g., you@company.com:your-api-token)

4. Click Test Connection to verify. You should see "Connection Successful".
5. Click Save to store the datasource.

Collections

After connecting, select a collection from the dropdown to query your Jira data.

Search Issues (JQL)

Searches for issues using JQL (Jira Query Language). This is the primary way to retrieve issue data from Jira and the foundation for most engineering and product analytics.

Parameters: 

• JQL Query – A JQL expression to filter issues. Examples:

  • project = MYPROJ — all issues in a project

  • assignee = currentUser() AND status != Done — your open issues

  • sprint in openSprints() — issues in active sprints

  • status changed TO Done DURING (-7d, now()) — resolved last 7 days (throughput)

  • issuetype = Bug AND created >= -30d — recent bugs

  • resolution = Unresolved AND created <= -14d — aging backlog

  • fixVersion = '2.5.0' — issues in a release

  • parent = EPIC-123 — issues under an epic

  • Leave blank to return all issues

• Page Size - Results per page (max 100). Knowi paginates automatically.
• Fields - Comma-separated list of fields to return. Default includes summary, status, assignee, priority, issuetype, project, reporter, labels, fixVersions, resolution, resolutiondate, duedate, components, and parent (epic). Use *all for all fields.
• Expand - Use changelog to get status transition history for cycle time and lead time analysis. Use names to discover custom field IDs (like story points).

Default Cloud9QL:

select expand(issues);
select key, expand(fields);
select key, summary, status.name as status, priority.name as priority, issuetype.name as issueType, assignee.displayName as assignee, reporter.displayName as reporter, project.name as project, resolution.name as resolution, resolutiondate, duedate, parent.key as epic, created, updated order by created desc;

The expand(issues) flattens the search results array, and expand(fields) unpacks the nested fields object within each issue.

Projects

Retrieves all projects visible to the authenticated user.

Default Cloud9QL:

select id, key, name, projectTypeKey, style, lead.displayName as lead;

Boards (Agile)

Retrieves boards from the Jira Agile API. Supports filtering by board type, project, and name.

Optional Filters: 

• Board Type - Filter by scrum, kanban, or simple
• Project Key or ID - Filter boards by project
• Board Name - Partial name match filter

Default Cloud9QL:

select expand(values);
select id, name, type, location.projectName as project;

Sprints

Retrieves sprints for a specific board. Use this to get sprint IDs for JQL queries like sprint = 123.

Required Parameters: 

• Board ID - The numeric ID of the Jira board. Get this from the Boards collection or from your Jira board URL

Optional Filters:

• Sprint State - Filter by active, future, or closed

Default Cloud9QL:

select expand(values);
select id, name, state, startDate, endDate, completeDate, goal order by startDate desc;

Issue Detail

Retrieves full details for a single issue, including description and all fields. Set Expand to changelog to get the full status transition history.

Required Parameters: 

• Issue Key - The issue key (e.g., MYPROJ-123) or numeric issue ID.

Default Cloud9QL:

select key, expand(fields);
select key, summary, status.name as status, priority.name as priority, assignee.displayName as assignee, reporter.displayName as reporter, issuetype.name as issueType, description, created, updated;

Custom Endpoint

For power users who need to access any Jira REST API endpoint not covered by the predefined collections.

Required Parameters: 

• API Path - The REST API path. Examples: 
  • rest/agile/1.0/sprint/{sprintId}/issue - issues in a specific sprint (useful for velocity)
  • rest/agile/1.0/epic/{epicKey}/issue - issues under an epic
  • rest/api/3/user/search - search users 
  • rest/api/3/priority - list priorities 
  • rest/api/3/status - list all statuses 
  • rest/api/3/resolution - list resolutions
  • rest/api/3/field - list all fields (use to find story points field ID)

Refer to the Jira REST API v3 documentation for all available endpoints.

Engineering & Product Analytics

This section covers common metrics that engineering managers, product managers, and VPs of Engineering track from Jira. Each recipe includes the JQL query, Cloud9QL transformation, and suggested visualization.

Sprint Velocity

Track story points completed per sprint to forecast capacity and identify trends.

Step 1: Find your story points field. Story points are stored in a custom field whose ID varies by Jira instance (commonly customfield_10016). To discover yours: 

1. Create a query with the Search Issues collection
2. Set Fields to *all and Expand to names 
3. Preview - look for a field named "Story Points", "Story point estimate", or similar
4. The names expansion maps field IDs to display names

Step 2: Query sprint issues with story points.

JQL:

sprint in closedSprints() AND project = MYPROJ

Fields: summary,status,issuetype,customfield_10016,sprint,resolutiondate

Cloud9QL:

select expand(issues);
select key, expand(fields);
select key, summary, status.name as status, issuetype.name as issueType,
  customfield_10016 as storyPoints, sprint.name as sprintName,
  sprint.startDate as sprintStart, sprint.endDate as sprintEnd,
  resolutiondate
where status = 'Done';
select sprintName, sprintStart, count(*) as issuesCompleted,
  sum(storyPoints) as totalPoints
group by sprintName, sprintStart
order by sprintStart asc;

Visualization: Bar chart with sprintName on X-axis, totalPoints on Y-axis. Add a trend line to see if velocity is improving.

Cycle Time & Lead Time

Lead time = time from issue creation to resolution. Cycle time = time from when work started (status changed to "In Progress") to resolution.

Lead time (simpler - no changelog needed):

JQL:

project = MYPROJ AND resolution = Done AND resolutiondate >= -90d

Fields: summary,issuetype,created,resolutiondate,priority

Cloud9QL:

select expand(issues);
select key, expand(fields);
select key, summary, issuetype.name as issueType, priority.name as priority,
  created, resolutiondate,
  datediff(resolutiondate, created, 'day') as leadTimeDays;
select issueType, avg(leadTimeDays) as avgLeadTime,
  percentile(leadTimeDays, 50) as medianLeadTime,
  percentile(leadTimeDays, 85) as p85LeadTime,
  count(*) as issueCount
group by issueType;

Visualization: Table showing avg/median/p85 lead time by issue type. Or histogram of leadTimeDays for distribution.

Cycle time (requires changelog expansion): Set Expand to changelog in the Search Issues parameters. This adds status transition history to each issue.

Throughput & Flow

Track how many issues are completed per day/week to measure team output.

JQL:

project = MYPROJ AND status changed TO Done DURING (-30d, now())

Fields: summary,status,issuetype,resolutiondate,assignee

Cloud9QL:

select expand(issues);
select key, expand(fields);
select key, issuetype.name as issueType, assignee.displayName as assignee,
  date_format(resolutiondate, 'yyyy-MM-dd') as resolvedDate;
select resolvedDate, count(*) as issuesResolved
group by resolvedDate
order by resolvedDate asc;

Visualization: Area chart showing daily throughput. Add a 7-day rolling average to smooth spikes.

Bug & Defect Tracking

Track bug creation rate, resolution rate, and open bug count over time.

Bug creation rate (last 90 days):

JQL:

project = MYPROJ AND issuetype = Bug AND created >= -90d

Cloud9QL:

select expand(issues);
select key, expand(fields);
select date_format(created, 'yyyy-ww') as week,
  priority.name as priority, count(*) as bugsCreated
group by week, priority
order by week asc;

Open bugs by priority:

JQL:

project = MYPROJ AND issuetype = Bug AND resolution = Unresolved

Cloud9QL:

select expand(issues);
select key, expand(fields);
select priority.name as priority, count(*) as openBugs
group by priority
order by openBugs desc;

Bug escape rate (bugs found after release):

JQL:

project = MYPROJ AND issuetype = Bug AND labels = production-bug AND created >= -30d

Team Workload & Capacity

See how work is distributed across the team to identify bottlenecks and overallocation.

Work in progress per assignee:

JQL:

project = MYPROJ AND status != Done AND status != Closed AND assignee is not EMPTY

Cloud9QL:

select expand(issues);
select key, expand(fields);
select assignee.displayName as assignee, status.name as status,
  issuetype.name as issueType, count(*) as issueCount
group by assignee, status, issueType
order by issueCount desc;

Visualization: Stacked bar chart with assignee on X-axis, issue count on Y-axis, colored by status. Immediately shows who has too many open items.

Issues completed per person per sprint:

JQL:

sprint in openSprints() AND project = MYPROJ

Cloud9QL:

select expand(issues);
select key, expand(fields);
select assignee.displayName as assignee, status.name as status, count(*) as count
group by assignee, status;

Backlog Health & Aging

Identify stale items that have been sitting unresolved for too long.

Aging backlog (unresolved issues older than 30 days):

JQL:

project = MYPROJ AND resolution = Unresolved AND created <= -30d ORDER BY created ASC

Cloud9QL:

select expand(issues);
select key, expand(fields);
select key, summary, issuetype.name as issueType, priority.name as priority,
  assignee.displayName as assignee, created,
  datediff(now(), created, 'day') as ageDays
order by ageDays desc;

Backlog age distribution:

select
  case
    when ageDays <= 7 then '0-7 days'
    when ageDays <= 30 then '8-30 days'
    when ageDays <= 90 then '31-90 days'
    else '90+ days'
  end as ageBucket,
  count(*) as issueCount
group by ageBucket;

Visualization: Pie chart or donut chart. If 90+ days is growing, the team is accumulating debt.

Release & Version Tracking

Track progress toward a release by fix version.

JQL:

fixVersion = '2.5.0'

Cloud9QL:

select expand(issues);
select key, expand(fields);
select status.name as status, issuetype.name as issueType, count(*) as count
group by status, issueType
order by status asc;

Release burndown:

select expand(issues);
select key, expand(fields);
select count(*) as totalIssues,
  sum(case when resolution.name is not null then 1 else 0 end) as resolved,
  sum(case when resolution.name is null then 1 else 0 end) as remaining;

Epic & Initiative Progress

Track completion across epics for roadmap visibility.

JQL:

project = MYPROJ AND issuetype in (Story, Task, Bug) AND parent is not EMPTY

Cloud9QL:

select expand(issues);
select key, expand(fields);
select parent.fields.summary as epicName, parent.key as epicKey,
  status.name as status, count(*) as count
group by epicName, epicKey, status
order by epicName asc;

Epic completion percentage:

select epicName, epicKey,
  count(*) as total,
  sum(case when status = 'Done' then 1 else 0 end) as done,
  round(sum(case when status = 'Done' then 1 else 0 end) * 100.0 / count(*), 1) as pctComplete
group by epicName, epicKey
order by pctComplete desc;

Discovering Story Points & Custom Fields

Story points are stored in a custom field whose ID varies by Jira instance. To discover the field ID:

1. Use the Custom Endpoint collection with API Path: rest/api/3/field
2. Preview the results
3. Search for "story" or "point" in the results. The id column shows the field ID (e.g., customfield_10016)
4. Use that field ID in the Fields parameter and Cloud9QL

Alternatively, query any issue with Fields set to *all and Expand set to names. The names expansion maps every custom field ID to its display name.

Common custom fields for engineering teams:

• Story Points / Story point estimate: customfield_10016 (most common on Jira Cloud)
• Sprint: sprint (standard field on Agile boards)
• Epic Link: parent (Jira Cloud next-gen) or customfield_10014 (classic)
• Team: varies by instance

Querying

After selecting a collection, click Preview to see the data. Use the Cloud9QL editor to transform and filter the results.

Common transformations:

• Flatten nested data: select expand(issues);
• Expand fields: select key, expand(fields);
• Select specific fields: select key, summary, status.name as status;
• Filter by date: select * where created >= '2024-01-01';
• Aggregate: select status, count(*) as count group by status;
• Date math: select datediff(resolutiondate, created, 'day') as leadTime;
• Conditional aggregation: select sum(case when status = 'Done' then 1 else 0 end) as done;

Cross-Source Joins

Jira data becomes most powerful when joined with other sources. Common patterns for engineering teams:

• Jira + GitHub: Join issues with pull requests and commits to measure PR-to-deploy cycle time, code review turnaround, and link commits to Jira tickets. JQL: use key to join with GitHub PR titles or branch names containing issue keys.
• Jira + CI/CD (REST API): Connect Jenkins, GitHub Actions, or CircleCI via REST API. Join build/deploy data with Jira releases to track deployment frequency (a DORA metric).
• Jira + PagerDuty/Opsgenie: Join incident data with bug tickets to measure mean time to resolve (MTTR) and correlate incidents with sprint work.
• Jira + SQL databases: Correlate project delivery with revenue, customer churn, or SLA data from your application database.
• Jira + Slack/Teams: Combine issue data with communication analytics to understand collaboration patterns.

To set up a cross-source join, see Joining Across Multiple Databases.

Building a Jira Engineering Dashboard

A typical engineering leadership dashboard combines multiple Jira queries:

1. Sprint Velocity (bar chart) - story points completed per sprint, last 6 sprints
2. Cycle Time Trend (line chart) - median lead time per week, last 12 weeks
3. Bug Rate (area chart) - bugs created vs resolved per week
4. Team Workload (stacked bar) - open issues per assignee by status
5. Backlog Health (donut chart) - issue age distribution
6. Release Progress (progress bar) - % complete for current release

Create each as a separate Knowi query with its own schedule (e.g., hourly), then combine them on a single dashboard. Use Knowi's dashboard filters to let viewers filter by project, team, or date range.

Schedule each query to run hourly or daily to keep the dashboard current. Knowi handles Jira's pagination automatically - even instances with 100K+ issues are fetched in full.

Scheduling

Once your query is configured, you can schedule it to run automatically (e.g., every hour, daily) to keep your dashboards up to date. Knowi handles pagination automatically - even large Jira instances with thousands of issues are fetched in full.

Recommended schedules for engineering dashboards:

• Sprint velocity / burndown: every 2 hours during business hours 
• Bug metrics: every 4 hours 
• Backlog health: daily 
• Release tracking: every 2 hours during release week, daily otherwise

Notes

• Authentication: Jira Cloud uses API tokens (not passwords). Generate tokens at id.atlassian.com under Security > API tokens.
• API Key Format: Enter the access token as email:apiToken (e.g., you@company.com:your-api-token). Knowi handles encoding automatically.
• Pagination: Jira uses offset-based pagination (startAt + maxResults). Knowi paginates automatically to fetch all results.
• Rate Limits: Jira Cloud allows approximately 450 requests per minute per user. Knowi's sequential pagination stays within this limit.
• JQL Reference: See Atlassian's JQL documentation for the full JQL syntax reference.
• Agile API: Boards and sprints use the Jira Software (Agile) REST API (/rest/agile/1.0/), which requires Jira Software to be enabled.
• Jira Server/Data Center: This connector is configured for Jira Cloud. For Jira Server or Data Center, use the Custom Endpoint collection with your server's base URL.
• Story Points: Story points are a custom field. Use rest/api/3/field via the Custom Endpoint to discover the field ID for your instance. See the "Discovering Story Points" section above.
• Changelog for Cycle Time: Set Expand to changelog in the Search Issues collection to get full status transition history. This enables precise cycle time calculations based on when issues actually moved between statuses.