Atlassian: Search for filters

← Filters operations · Get started

Operation atlassian.getfilterspaginated

Provider route: GET /{cloudId}/rest/api/3/filter/search. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/atlassian with npm, or alter-sdk-atlassian with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { AtlassianIntegration } from "@alter-ai/atlassian";

async function execute(input: Parameters<AtlassianIntegration["filters"]["getFiltersPaginated"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new AtlassianIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.filters.getFiltersPaginated(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_atlassian import AtlassianIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = AtlassianIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.filters.get_filters_paginated(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.cloudId	string	Required within parent	Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
query	object	Optional	Additional keys: not allowed
query.filterName	string	Optional
query.accountId	string	Optional	Maximum length: 128 Minimum length: 0
query.owner	string	Optional
query.groupname	string	Optional
query.groupId	string	Optional
query.projectId	integer	Optional	Format: int64
query.id	array	Optional	Unique items: true
query.id[]	integer	Each item	Format: int64
query.orderBy	string	Optional	Default: name One of: description, -description, +description, favourite_count, -favourite_count, +favourite_count, id, -id, +id, is_favourite, -is_favourite, +is_favourite, name, -name, +name, owner, -owner, +owner, is_shared, -is_shared, +is_shared
query.startAt	integer	Optional	Default: 0 Format: int64
query.maxResults	integer	Optional	Default: 50 Format: int32
query.expand	string	Optional
query.overrideSharePermissions	boolean	Optional	Default: false
query.isSubstringMatch	boolean	Optional	Default: false

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Search for filters — response body

Referenced models: Search for filters — response body

Schemas

29 more schemas are linked from the tables above, on the schema pages.

Search for filters — response body

Field	Type	Presence	Description and constraints
$	object	Root	A page of items.
isLast	JSON	Optional
isLast (anyOf 1)	boolean	Alternative	Whether this is the last page. Read only: true
isLast (anyOf 2)	null	Alternative
maxResults	JSON	Optional
maxResults (anyOf 1)	JSON	Alternative
maxResults (anyOf 1) (anyOf 1)	integer	Alternative	The maximum number of items that could be returned. Format: int32 Read only: true
maxResults (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
maxResults (anyOf 2)	null	Alternative
nextPage	JSON	Optional
nextPage (anyOf 1)	string	Alternative	If there is another page of results, the URL of the next page. Format: uri Read only: true
nextPage (anyOf 2)	null	Alternative
self	JSON	Optional
self (anyOf 1)	string	Alternative	The URL of the page. Format: uri Read only: true
self (anyOf 2)	null	Alternative
startAt	JSON	Optional
startAt (anyOf 1)	JSON	Alternative
startAt (anyOf 1) (anyOf 1)	integer	Alternative	The index of the first item returned. Format: int64 Read only: true
startAt (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
startAt (anyOf 2)	null	Alternative
total	JSON	Optional
total (anyOf 1)	JSON	Alternative
total (anyOf 1) (anyOf 1)	integer	Alternative	The number of items returned. Format: int64 Read only: true
total (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
total (anyOf 2)	null	Alternative
values	JSON	Optional
values (anyOf 1)	array	Alternative	The list of items. Read only: true
values (anyOf 1)[]	Model	Each item	Expand Search for filters — response body — values The list of items item
values (anyOf 2)	null	Alternative

Referenced models: Search for filters — response body — values The list of items item

Search for filters — response body — values The list of items item

Field	Type	Presence	Description and constraints
$	object	Root	Details of a filter.
approximateLastUsed	JSON	Optional
approximateLastUsed (anyOf 1)	JSON	Alternative
approximateLastUsed (anyOf 1) (anyOf 1)	string	Alternative	\[Experimental\] Approximate last used time. Returns the date and time when the filter was last used. Returns `null` if the filter hasn't been used after tracking was enabled. For performance reasons, timestamps aren't updated in real time and therefore may not be exactly accurate. Read only: true
approximateLastUsed (anyOf 1) (anyOf 2)	integer	Alternative
approximateLastUsed (anyOf 2)	null	Alternative
description	JSON	Optional
description (anyOf 1)	string	Alternative	The description of the filter.
description (anyOf 2)	null	Alternative
editPermissions	JSON	Optional
editPermissions (anyOf 1)	array	Alternative	The groups and projects that can edit the filter. This can be specified when updating a filter, but not when creating a filter.
editPermissions (anyOf 1)[]	Model	Each item	Expand Get share permission — response body
editPermissions (anyOf 2)	null	Alternative
expand	JSON	Optional
expand (anyOf 1)	string	Alternative	Expand options that include additional filter details in the response. Read only: true
expand (anyOf 2)	null	Alternative
favourite	JSON	Optional
favourite (anyOf 1)	boolean	Alternative	Whether the filter is selected as a favorite by any users, not including the filter owner. Read only: true
favourite (anyOf 2)	null	Alternative
favouritedCount	JSON	Optional
favouritedCount (anyOf 1)	JSON	Alternative
favouritedCount (anyOf 1) (anyOf 1)	integer	Alternative	The count of how many users have selected this filter as a favorite, including the filter owner. Format: int64 Read only: true
favouritedCount (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
favouritedCount (anyOf 2)	null	Alternative
id	JSON	Optional
id (anyOf 1)	string	Alternative	The unique identifier for the filter. Read only: true
id (anyOf 2)	null	Alternative
jql	JSON	Optional
jql (anyOf 1)	string	Alternative	The JQL query for the filter. For example, *project = SSP AND issuetype = Bug*. Read only: true
jql (anyOf 2)	null	Alternative
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the filter.
name (anyOf 2)	null	Alternative
owner	JSON	Optional
owner (anyOf 1)	Model	Alternative	Expand Get user — response body The user who owns the filter. Defaults to the creator of the filter, however, Jira administrators can change the owner of a shared filter in the admin settings. Read only: true
owner (anyOf 2)	null	Alternative
searchUrl	JSON	Optional
searchUrl (anyOf 1)	string	Alternative	A URL to view the filter results in Jira, using the [Search for issues using JQL](#api-rest-api-3-filter-search-get) operation with the filter's JQL string to return the filter results. For example, *https://your-domain.atlassian.net/rest/api/3/search?jql=project+%3D+SSP+AND+issuetype+%3D+Bug*. Format: uri Read only: true
searchUrl (anyOf 2)	null	Alternative
self	JSON	Optional
self (anyOf 1)	string	Alternative	The URL of the filter. Format: uri Read only: true
self (anyOf 2)	null	Alternative
sharePermissions	JSON	Optional
sharePermissions (anyOf 1)	array	Alternative	The groups and projects that the filter is shared with. This can be specified when updating a filter, but not when creating a filter.
sharePermissions (anyOf 1)[]	Model	Each item	Expand Get share permission — response body
sharePermissions (anyOf 2)	null	Alternative
subscriptions	JSON	Optional
subscriptions (anyOf 1)	array	Alternative	The users that are subscribed to the filter. Read only: true
subscriptions (anyOf 1)[]	Model	Each item	Expand Get filter — response body — subscriptions A paginated list of subscriptions to a filter items The list of items item
subscriptions (anyOf 2)	null	Alternative
viewUrl	JSON	Optional
viewUrl (anyOf 1)	string	Alternative	A URL to view the filter results in Jira, using the ID of the filter. For example, *https://your-domain.atlassian.net/issues/?filter=10100*. Format: uri Read only: true
viewUrl (anyOf 2)	null	Alternative

Referenced models: Get filter — response body — subscriptions A paginated list of subscriptions to a filter items The list of items item, Get share permission — response body, Get user — response body

Get filter — response body — subscriptions A paginated list of subscriptions to a filter items The list of items item

Field	Type	Presence	Description and constraints
$	object	Root	Details of a user or group subscribing to a filter.
group	JSON	Optional
group (anyOf 1)	Model	Alternative	Expand Get user groups — response body — item The group subscribing to filter. Read only: true
group (anyOf 2)	null	Alternative
id	JSON	Optional
id (anyOf 1)	JSON	Alternative
id (anyOf 1) (anyOf 1)	integer	Alternative	The ID of the filter subscription. Format: int64 Read only: true
id (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
id (anyOf 2)	null	Alternative
user	JSON	Optional
user (anyOf 1)	Model	Alternative	Expand Get user — response body The user subscribing to filter. Read only: true
user (anyOf 2)	null	Alternative

Referenced models: Get user groups — response body — item, Get user — response body

Get project — response body — permissions Permissions which a user has on a project

Field	Type	Presence	Description and constraints
$	object	Root	Permissions which a user has on a project.
canEdit	JSON	Optional
canEdit (anyOf 1)	boolean	Alternative	Whether the logged user can edit the project. Read only: true
canEdit (anyOf 2)	null	Alternative

Policy, approvals and errors

SDK function policy ID: atlassian.getfilterspaginated. Catalog operation: getfilterspaginated. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["read:jira-work"]

Official provider source