---
title: "Find various JIRA entities relevant to the specified date interval."
method: POST
path: "/filter/jira"
tags: ["filter", "default"]
---

# Find various JIRA entities relevant to the specified date interval.

`POST /filter/jira`

## Request

- Base URL: `{{ server_url }}/v1`
- URL: `{{ server_url }}/v1/filter/jira`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/athenian/apis/title/docs/filter/jira/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- FilterJIRAStuff: Request of `/filter/jira` to retrieve epics, labels, types, priorities, users, etc.
  - `account` integer, required: Session account ID.
  - `date_from` string, date, nullable, required: `null` disables the time filter boundary, thus everything is returned. `date_from` and `date_to` must be both either `null` or not `null`.
  - `date_to` string, date, nullable, required: `null` disables the time filter boundary, thus everything is returned. `date_from` and `date_to` must be both either `null` or not `null`.
  - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
  - `priorities` string[]: Selected issue priorities.
  - `types` string[]: Selected issue types. Ignored for epics.
  - `labels_include` string[]: JIRA issues must contain at least one label from the list. Several labels may be concatenated by a comma `,` so that all of them are required.
  - `labels_exclude` string[]: JIRA issues may not contain labels from this list.
  - `exclude_inactive` boolean, required: Value indicating whether issues with the last update older than `date_from` should be ignored. If `date_from` and `date_to` are `null`, does nothing.
  - `with` object: Group of JIRA issue participant names split by role.
    - `assignees` string[]: Selected issue assignee users. `null` means unassigned.
    - `reporters` string[]: Selected issue reporter users.
    - `commenters` string[]: Selected issue commenter users.
  - `projects` string[]: Issues must belong to these JIRA projects.
  - `return` JIRAFilterReturn[]: Specifies which items are required, an empty or missing array means everything.

## Response `200`

List of found JIRA entities, ordered by the last usage time.

- FilteredJIRAStuff: Response from `/filter/jira`: found JIRA epics, labels, issue types, priorities, and mentioned users.
  - `epics` JIRAEpic[], required: List of epics satisfying the filters.
    - `id` string, required: JIRA issue key `PROJECT-###`.
    - `title` string, required: Title of this issue.
    - `created` string, date-time, required: When this issue was created.
    - `updated` string, date-time, required: When this issue was last updated.
    - `work_began` string, date-time: When the issue entered the "In Progress" stage or received a PR. This timestamp can be missing and is always less than or equal to `resolved`.
    - `resolved` string, date-time: When the issue finished: the stage is "Done" and all PRs are either released or rejected. This timestamp can be missing and is always greater than or equal to `work_began`.
    - `acknowledge_time` string, required: Time duration value.
    - `lead_time` string: Time duration value.
    - `life_time` string, required: Time duration value.
    - `reporter` string, required: Name of the person who reported the issue.
    - `assignee` string: Name of the assigned person.
    - `comments` integer, required: Number of comments in the issue excluding sub-tasks and children.
    - `comment_list` JIRAComment[]: The list of comments for the issue.
      - `author` string, required: The name of the user who created the comment.
      - `created` string, date-time, required: The date and time at which the comment was created.
      - `rendered_body` string, required: The comment text.
    - `priority` string, nullable, required: Name of the priority. The details are returned in `FilteredJIRAStuff.priorities`.
    - `rendered_description` string: The description of the issue rendered as HTML.
    - `status` string, required: Name of the status. The details are returned in `FilteredJIRAStuff.statuses`.
    - `story_points` number: Value of the "story points" field.
    - `type` string, required: Name of the issue type. The details are returned in `FilteredJIRAStuff.issue_types`.
    - `url` string, url, required: Link to the issue in JIRA web application.
    - `project` string, required: Identifier of the project where this epic exists.
    - `children` JIRAEpicChild[]: Details about the child issues.
      - `id` string, required: JIRA issue key `PROJECT-###`.
      - `title` string, required: Title of this issue.
      - `created` string, date-time, required: When this issue was created.
      - `updated` string, date-time, required: When this issue was last updated.
      - `work_began` string, date-time: When the issue entered the "In Progress" stage or received a PR. This timestamp can be missing and is always less than or equal to `resolved`.
      - `resolved` string, date-time: When the issue finished: the stage is "Done" and all PRs are either released or rejected. This timestamp can be missing and is always greater than or equal to `work_began`.
      - `acknowledge_time` string, required: Time duration value.
      - `lead_time` string: Time duration value.
      - `life_time` string, required: Time duration value.
      - `reporter` string, required: Name of the person who reported the issue.
      - `assignee` string: Name of the assigned person.
      - `comments` integer, required: Number of comments in the issue excluding sub-tasks and children.
      - `comment_list` JIRAComment[]: The list of comments for the issue.
        - `author` string, required: The name of the user who created the comment.
        - `created` string, date-time, required: The date and time at which the comment was created.
        - `rendered_body` string, required: The comment text.
      - `priority` string, nullable, required: Name of the priority. The details are returned in `FilteredJIRAStuff.priorities`.
      - `rendered_description` string: The description of the issue rendered as HTML.
      - `status` string, required: Name of the status. The details are returned in `FilteredJIRAStuff.statuses`.
      - `story_points` number: Value of the "story points" field.
      - `type` string, required: Name of the issue type. The details are returned in `FilteredJIRAStuff.issue_types`.
      - `url` string, url, required: Link to the issue in JIRA web application.
      - `subtasks` integer, required: Number of sub-tasks.
      - `prs` integer, required: Number of mapped pull requests.
    - `prs` integer, required: Overall number of mapped pull requests (including the children).
  - `issues` JIRAIssue[], required: List of issues satisfying the filters.
    - `id` string, required: JIRA issue key `PROJECT-###`.
    - `title` string, required: Title of this issue.
    - `created` string, date-time, required: When this issue was created.
    - `updated` string, date-time, required: When this issue was last updated.
    - `work_began` string, date-time: When the issue entered the "In Progress" stage or received a PR. This timestamp can be missing and is always less than or equal to `resolved`.
    - `resolved` string, date-time: When the issue finished: the stage is "Done" and all PRs are either released or rejected. This timestamp can be missing and is always greater than or equal to `work_began`.
    - `acknowledge_time` string, required: Time duration value.
    - `lead_time` string: Time duration value.
    - `life_time` string, required: Time duration value.
    - `reporter` string, required: Name of the person who reported the issue.
    - `assignee` string: Name of the assigned person.
    - `comments` integer, required: Number of comments in the issue excluding sub-tasks and children.
    - `comment_list` JIRAComment[]: The list of comments for the issue.
      - `author` string, required: The name of the user who created the comment.
      - `created` string, date-time, required: The date and time at which the comment was created.
      - `rendered_body` string, required: The comment text.
    - `priority` string, nullable, required: Name of the priority. The details are returned in `FilteredJIRAStuff.priorities`.
    - `rendered_description` string: The description of the issue rendered as HTML.
    - `status` string, required: Name of the status. The details are returned in `FilteredJIRAStuff.statuses`.
    - `story_points` number: Value of the "story points" field.
    - `type` string, required: Name of the issue type. The details are returned in `FilteredJIRAStuff.issue_types`.
    - `url` string, url, required: Link to the issue in JIRA web application.
    - `project` string, required: Identifier of the project where this issue exists.
    - `prs` PullRequest[]: Details about the mapped PRs. `jira` field is unfilled.
      - `repository` string, required: PR is/was open in this repository.
      - `number` integer, required: PR number.
      - `title` string, required: Title of the PR.
      - `size_added` integer, required: Overall number of lines added.
      - `size_removed` integer, required: Overall number of lines removed.
      - `files_changed` integer, required: Number of files changed in this PR.
      - `created` string, date-time, required: When this PR was created.
      - `updated` string, date-time, required: When this PR was last updated.
      - `closed` string, date-time: When this PR was last closed.
      - `comments` integer, required: Number of *regular* (not review) comments in this PR.
      - `commits` integer, required: Number of commits in this PR.
      - `review_requested` string, date-time: When was the first time the author of this PR requested a review.
      - `first_review` string, date-time: When the first review of this PR happened.
      - `approved` string, date-time: When this PR was approved.
      - `review_comments` integer: Number of review comments this PR received. A review comment is left at a specific line in a specific file. In other words: review summaries are *not* considered review comments; refer to `reviews`. Comments by the PR author are considered as `comments`, not as `review_comments`.
      - `reviews` integer: Number of times this PR was reviewed. Reviews by the PR author are not taken into account.
      - `merged` string, date-time: When this PR was merged.
      - `merged_with_failed_check_runs` string[]: PR was merged with these failed check runs.
      - `released` string, date-time: When this PR was released.
      - `release_url` string, url: URL of the earliest release that includes this merged PR.
      - `deployments` string[]: List of deployments that contain this PR.
      - `stage_timings` StageTimings, required: Time spent by the PR in each pipeline stage. The deployments are independent of the releases. If the release happens before the deployment, the deployment time measures from the release event. If the release happens after the deployment, the two values are independent and both measure from the PR merge event.
        - `wip` string, required: Time duration value.
        - `review` string: Time duration value.
        - `merge` string: Time duration value.
        - `release` string: Time duration value.
        - `deploy` object: Map from target environments to the values.
      - `events_time_machine` PullRequestEvent[]: List of PR events which happened until `date_to`. `date_from` does not matter.
      - `stages_time_machine` PullRequestStage[]: List of PR stages as of `date_to` (normally, of length 1).
      - `events_now` PullRequestEvent[], required: List of PR events that ever happened.
      - `stages_now` PullRequestStage[], required: List of current PR stages (normally, of length 1).
      - `participants` PullRequestParticipant[], required: List of developers related to this PR.
        - `id` string, required: Person identifier.
        - `status` string[], required
      - `labels` PullRequestLabel[]: List of PR labels.
        - `name` string, required
        - `description` string
        - `color` string, required: RGB 24-bit color in hex.
      - `jira` LinkedJIRAIssue[]: List of linked JIRA issues.
        - `id` string, required: JIRA issue key `PROJECT-###`.
        - `title` string, required: Title of this issue.
        - `epic` string: Identifier of the epic that owns this issue.
        - `labels` string[]: List of JIRA labels in this issue.
        - `type` string, required: Type of this issue.
  - `issue_types` JIRAIssueType[], required: Mentioned issue types.
    - `name` string, required: Name of the issue type.
    - `normalized_name` string, required: Normalized name of the issue type. For example, "Sub-tásks" becomes "subtask".
    - `count` integer, required: Number of issues that satisfy the filters and belong to this type.
    - `image` string, url, required: Icon URL.
    - `project` string, required: Bound project identifier.
    - `is_subtask` boolean, required: Value indicating whether this issue type refers to a sub-task.
    - `is_epic` boolean, required: Value indicating whether this issue type refers to an epic.
  - `labels` JIRALabel[], required: Mentioned issue labels.
    - `title` string, required
    - `last_used` string, date-time, required: When this label was last assigned to an issue.
    - `issues_count` integer, required: In how many issues (in the specified time interval) this label was used.
    - `kind` string: Label kind - "Label", "Component", etc.
  - `priorities` JIRAPriority[], required: Mentioned issue priorites sorted by importance in ascending order.
    - `name` string, required: Name of the priority.
    - `image` string, url, required: URL of the picture that indicates the priority.
    - `rank` integer, required: Measure of importance (smaller is more important).
    - `color` string, required: RGB 24-bit color in hex.
  - `statuses` JIRAStatus[], required: Mentioned issue statuses sorted by name.
    - `name` string, required: Exact status name.
    - `stage` 'To Do' | 'In Progress' | 'Done' | 'No Category', required: The category of a JIRA issue status.
    - `project` string, required: Identifier of the project where this status exists.
  - `users` JIRAUser[], required: Mentioned users in the filtered issues.
    - `name` string, required: Full name of the user.
    - `avatar` string, url, required: User's profile picture URL.
    - `type` 'atlassian' | 'app' | 'customer', required: * `atlassian` indicates a regular account backed by a human. * `app` indicates a service account. * `customer` indicates an external service desk account.
    - `developer` string: Mapped developer identity.
  - `deployments` IncludedDeployments: Mentioned deployments.
    - `deployments` object: Mapping deployment names to their details.

## Other responses

- `403`: The user is not an account member.
- `404`: The account was not found.

## Changes

- **2023-04-14** `4dcbf99639b4`: 3 info
  - added the required property `epics/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/acknowledge_time` to the response with the `200` status
  - added the required property `epics/items/allOf[subschema #2]/children/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/acknowledge_time` to the response with the `200` status
  - added the required property `issues/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/acknowledge_time` to the response with the `200` status
- **2023-03-10** `0cc28e1bffc4`: 3 info
  - added the optional property `epics/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/rendered_description` to the response with the `200` status
  - added the optional property `epics/items/allOf[subschema #2]/children/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/rendered_description` to the response with the `200` status
  - added the optional property `issues/items/allOf[#/components/schemas/JIRAEpicIssueCommon]/rendered_description` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/athenian/apis/title/changes/filter/jira/post.md)

---

[API](https://skmtc.dev/athenian/apis/title.md) - [All operations](https://skmtc.dev/athenian/apis/title/llms.txt) - [OpenAPI document](https://skmtc.dev/athenian/apis/title/revisions/110c9f7cffdd?raw)