> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# QueryAppInstallations

# Package: appInstallations

# Namespace: AppInstallations

# Method link: https://dev.wix.com/docs/api-reference/app-management/app-installations/query-app-installations.md

## Permission Scopes:
Read App Installations: SCOPE.APP_MARKET.READ_APP_INSTALLATIONS

## Introduction

Retrieves a list of up to 100 app installations, with the specified paging, filtering, and sorting.

Query App Installations runs with these defaults, which you can override:
- `createdDate` is sorted in `DESC` order
- `paging.limit` is `50`

The results include installations across all the apps in your developer account.

To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).
For a free-text search across a number of fields, use [Search App Installation](https://dev.wix.com/docs/api-reference/app-management/app-installations/search-app-installation.md).

---

## REST API

### Schema

```
 Method: queryAppInstallations
 Description: Retrieves a list of up to 100 app installations, with the specified paging, filtering, and sorting.  Query App Installations runs with these defaults, which you can override: - `createdDate` is sorted in `DESC` order - `paging.limit` is `50`  The results include installations across all the apps in your developer account.  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). For a free-text search across a number of fields, use [Search App Installation](https://dev.wix.com/docs/api-reference/app-management/app-installations/search-app-installation.md).
 URL: https://www.wixapis.com/v1/app-installations/query
 Method: POST
 Method parameters:
   param name: fields | type: array<fields> | description: Additional fields to include in the response.  | validation: maxItems 1
                 - enum:
                 -     OWNER_EMAIL: Include `siteInfo.ownerEmail` in each returned app installation.  Note: Only returns if your app has the **Get Site Owner** permission.
   param name: query | type: CursorQuery    
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.  
        - name: limit | type: integer | description: Maximum number of items to return in the results.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  | validation: maxLength 16000
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`  
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]`  | validation: maxItems 5
           - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
           - name: order | type: SortOrder | description: Sort order.  
                 - enum: ASC, DESC
 Return type: QueryAppInstallationsResponse
  - name: appInstallations | type: array<AppInstallation> | description: Retrieved app installations.  
     - name: id | type: string | description: App installation GUID.  | validation: format GUID
     - name: instanceId | type: string | description: Unique identifier of the app instance on the site. Stable across uninstalls and reinstalls of the same app on the same site.  | validation: format GUID
     - name: createdDate | type: string | description: Date and time the app installation was created.  | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the app installation was last updated.  | validation: format date-time
     - name: revision | type: string | description: Revision number, which increments by 1 each time the app installation is updated.  | validation: format int64
     - name: firstInstallationDate | type: string | description: Date and time the app was first installed on the site. Preserved across uninstalls and reinstalls.  | validation: format date-time
     - name: siteInfo | type: SiteInfo | description: Information about the site the app is installed on.  
        - name: siteId | type: string | description: Site GUID.  | validation: format GUID
        - name: businessName | type: string | description: Business name displayed on the site.  | validation: maxLength 100
        - name: siteUrl | type: string | description: Public URL of the site.  | validation: format WEB_URL
        - name: businessEmail | type: string | description: Business email address configured on the site.  | validation: format EMAIL
        - name: countryCode | type: string | description: 2-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.  | validation: format COUNTRY
        - name: businessCategory | type: Categories | description: Business category the site belongs to.  
           - name: primary | type: string | description: Primary site category.  | validation: maxLength 100
           - name: secondary | type: array | description: Secondary site category.  | validation: maxItems 50, maxLength 100
        - name: premium | type: boolean | description: Whether the site has an active Premium subscription.  
        - name: editorType | type: EditorType | description: Editor the site was created with.  
             - enum:
             -     EDITOR: Wix Editor.
             -     ADI: Wix ADI.
             -     EDITORX: Editor X.
             -     STUDIO: Wix Studio.
             -     HARMONY: Wix Harmony.
             -     VIBE: Wix Vibe.
             -     WIXEL: Wixel.
        - name: ownerEmail | type: string | description: Email address of the site owner. Returned only when `OWNER_EMAIL` is requested in the `fields` parameter and the app has the **Get Site Owner** permission.  | validation: format EMAIL
        - name: accountId | type: string | description: GUID of the site owner's account.  | validation: format GUID
     - name: planInfo | type: PlanInfo | description: Information about the plan the site owner purchased for the app.  
        - name: planName | type: string | description: Name of the plan the site owner purchased for the app.  | validation: maxLength 100
        - name: billingCycle | type: Cycle | description: Billing cycle of the purchased plan.  
           - name: cycleType | type: CycleType | description: Type of the billing cycle.  + `"UNKNOWN_UNIT"`:  There is no information about the billing cycle. + `"ONE_TIME"`:  The customer pays for unlimited usage of the app with a single payment. + `"RECURRING"`: The customer pays for a subscription to the app on a recurring schedule.  
                 - enum: ONE_TIME, RECURRING
           - name: cycleDuration | type: Duration | description: Duration of the billing cycle. Available only for `{"cycleType": "RECURRING"}`.  
              - name: unit | type: DurationUnit | description: Unit of the billing cycle.  
                     - enum:
                     -     MONTH: Month.
                     -     YEAR: Year.
              - name: count | type: integer | description: Count of units that make up the billing cycle.  | validation: minimum 0
        - name: planStatus | type: PlanStatus | description: Current status of the purchased plan.  
             - enum:
             -     UPGRADED: The site owner upgraded the app to a paid plan.
             -     CANCELED: The site owner upgraded the app to a paid plan and has since canceled it.
             -     AUTO_RENEW_OFF: The plan is still active, but auto-renewal is turned off.
        - name: freeTrialInfo | type: FreeTrialInfo | description: Free trial details for the purchased plan, if a free trial is or was active.  
           - name: status | type: FreeTrialStatus | description: Current free trial status.  
                 - enum:
                 -     IN_PROGRESS: The free trial is currently in progress.
                 -     ENDED: The free trial has ended.
           - name: endDate | type: string | description: Date and time the free trial ended.  Returned only after the free trial has ended.  | validation: format date-time
        - name: endDate | type: string | description: Date and time the plan expires.  Returned only when auto-renewal is turned off.  | validation: format date-time
     - name: appId | type: string | description: GUID of the installed app.  | validation: format GUID
     - name: appVersion | type: string | description: Major version of the installed app.  | validation: maxLength 6
     - name: status | type: Status | description: Current installation status of the app on the site.  
         - enum:
         -     INSTALLED: The app is currently installed on the site.
         -     UNINSTALLED: The app was installed on the site and has since been removed.
     - name: review | type: ReviewInfo | description: Information about the review the site owner left for the app, if any.  
        - name: id | type: string | description: Review GUID.  | validation: format GUID
        - name: date | type: string | description: Date and time the review was published.  | validation: format date-time
        - name: rating | type: integer | description: Rating the site owner left for the app, from 1 to 5.  | validation: format int32
        - name: title | type: string | description: Review title.  | validation: maxLength 100
        - name: description | type: string | description: Review body text.  | validation: maxLength 2500
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata, including the cursor used to retrieve the next page of results.  
     - name: count | type: integer | description: Number of items returned in current page.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page.  


```

### Examples

### Query App Installations
Retrieves currently installed instances of a specific app, sorted by most recent first.

```curl
curl -X POST \
  'https://www.wixapis.com/app-installations/v1/app-installations/query' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "query": {
      "filter": {
        "appId": { "$eq": "2b4d6452-e1a7-4f28-9747-13d77225e6b6" },
        "status": { "$eq": "INSTALLED" }
      },
      "sort": [
        { "fieldName": "createdDate", "order": "DESC" }
      ],
      "cursorPaging": {
        "limit": 50
      }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.appInstallations.AppInstallations.queryAppInstallations(query, options)
 Description: Retrieves a list of up to 100 app installations, with the specified paging, filtering, and sorting.  Query App Installations runs with these defaults, which you can override: - `createdDate` is sorted in `DESC` order - `paging.limit` is `50`  The results include installations across all the apps in your developer account.  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md). For a free-text search across a number of fields, use [Search App Installation](https://dev.wix.com/docs/api-reference/app-management/app-installations/search-app-installation.md).
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  query
 Method parameters: 
   param name: options | type: QueryAppInstallationsOptions  none  
        - name: fields | type: array<RequestedFields> | description: Additional fields to include in the response.  | validation: maxItems 1
             - enum:
             -     OWNER_EMAIL: Include `siteInfo.ownerEmail` in each returned app installation.  Note: Only returns if your app has the **Get Site Owner** permission.
   param name: query | type: AppInstallationQuery   | required: true 
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.  
        - name: limit | type: integer | description: Maximum number of items to return in the results.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  | validation: maxLength 16000
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`  
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]`  | validation: maxItems 5
           - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
           - name: order | type: SortOrder | description: Sort order.  
                 - enum: ASC, DESC
 Return type: PROMISE<QueryAppInstallationsResponse>
  - name: appInstallations | type: array<AppInstallation> | description: Retrieved app installations.  
     - name: _id | type: string | description: App installation GUID.  | validation: format GUID
     - name: instanceId | type: string | description: Unique identifier of the app instance on the site. Stable across uninstalls and reinstalls of the same app on the same site.  | validation: format GUID
     - name: _createdDate | type: Date | description: Date and time the app installation was created.  
     - name: _updatedDate | type: Date | description: Date and time the app installation was last updated.  
     - name: revision | type: string | description: Revision number, which increments by 1 each time the app installation is updated.  | validation: format int64
     - name: firstInstallationDate | type: Date | description: Date and time the app was first installed on the site. Preserved across uninstalls and reinstalls.  
     - name: siteInfo | type: SiteInfo | description: Information about the site the app is installed on.  
        - name: siteId | type: string | description: Site GUID.  | validation: format GUID
        - name: businessName | type: string | description: Business name displayed on the site.  | validation: maxLength 100
        - name: siteUrl | type: string | description: Public URL of the site.  | validation: format WEB_URL
        - name: businessEmail | type: string | description: Business email address configured on the site.  | validation: format EMAIL
        - name: countryCode | type: string | description: 2-letter country code in [ISO-3166 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.  | validation: format COUNTRY
        - name: businessCategory | type: Categories | description: Business category the site belongs to.  
           - name: primary | type: string | description: Primary site category.  | validation: maxLength 100
           - name: secondary | type: array | description: Secondary site category.  | validation: maxItems 50, maxLength 100
        - name: premium | type: boolean | description: Whether the site has an active Premium subscription.  
        - name: editorType | type: EditorType | description: Editor the site was created with.  
             - enum:
             -     EDITOR: Wix Editor.
             -     ADI: Wix ADI.
             -     EDITORX: Editor X.
             -     STUDIO: Wix Studio.
             -     HARMONY: Wix Harmony.
             -     VIBE: Wix Vibe.
             -     WIXEL: Wixel.
        - name: ownerEmail | type: string | description: Email address of the site owner. Returned only when `OWNER_EMAIL` is requested in the `fields` parameter and the app has the **Get Site Owner** permission.  | validation: format EMAIL
        - name: accountId | type: string | description: GUID of the site owner's account.  | validation: format GUID
     - name: planInfo | type: PlanInfo | description: Information about the plan the site owner purchased for the app.  
        - name: planName | type: string | description: Name of the plan the site owner purchased for the app.  | validation: maxLength 100
        - name: billingCycle | type: Cycle | description: Billing cycle of the purchased plan.  
           - name: cycleType | type: CycleType | description: Type of the billing cycle.  + `"UNKNOWN_UNIT"`:  There is no information about the billing cycle. + `"ONE_TIME"`:  The customer pays for unlimited usage of the app with a single payment. + `"RECURRING"`: The customer pays for a subscription to the app on a recurring schedule.  
                 - enum: ONE_TIME, RECURRING
           - name: cycleDuration | type: Duration | description: Duration of the billing cycle. Available only for `{"cycleType": "RECURRING"}`.  
              - name: unit | type: DurationUnit | description: Unit of the billing cycle.  
                     - enum:
                     -     MONTH: Month.
                     -     YEAR: Year.
              - name: count | type: integer | description: Count of units that make up the billing cycle.  | validation: minimum 0
        - name: planStatus | type: PlanStatus | description: Current status of the purchased plan.  
             - enum:
             -     UPGRADED: The site owner upgraded the app to a paid plan.
             -     CANCELED: The site owner upgraded the app to a paid plan and has since canceled it.
             -     AUTO_RENEW_OFF: The plan is still active, but auto-renewal is turned off.
        - name: freeTrialInfo | type: FreeTrialInfo | description: Free trial details for the purchased plan, if a free trial is or was active.  
           - name: status | type: FreeTrialStatus | description: Current free trial status.  
                 - enum:
                 -     IN_PROGRESS: The free trial is currently in progress.
                 -     ENDED: The free trial has ended.
           - name: endDate | type: Date | description: Date and time the free trial ended.  Returned only after the free trial has ended.  
        - name: endDate | type: Date | description: Date and time the plan expires.  Returned only when auto-renewal is turned off.  
     - name: appId | type: string | description: GUID of the installed app.  | validation: format GUID
     - name: appVersion | type: string | description: Major version of the installed app.  | validation: maxLength 6
     - name: status | type: Status | description: Current installation status of the app on the site.  
         - enum:
         -     INSTALLED: The app is currently installed on the site.
         -     UNINSTALLED: The app was installed on the site and has since been removed.
     - name: review | type: ReviewInfo | description: Information about the review the site owner left for the app, if any.  
        - name: _id | type: string | description: Review GUID.  | validation: format GUID
        - name: date | type: Date | description: Date and time the review was published.  
        - name: rating | type: integer | description: Rating the site owner left for the app, from 1 to 5.  | validation: format int32
        - name: title | type: string | description: Review title.  | validation: maxLength 100
        - name: description | type: string | description: Review body text.  | validation: maxLength 2500
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata, including the cursor used to retrieve the next page of results.  
     - name: count | type: integer | description: Number of items returned in current page.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page.  


```

### Examples

### queryAppInstallations
```javascript
import { appInstallations } from '@wix/app-installations';

async function queryAppInstallations(query,options) {
  const response = await appInstallations.queryAppInstallations(query,options);
};
```

### queryAppInstallations (with elevated permissions)
```javascript
import { appInstallations } from '@wix/app-installations';
import { auth } from '@wix/essentials';

async function myQueryAppInstallationsMethod(query,options) {
  const elevatedQueryAppInstallations = auth.elevate(appInstallations.queryAppInstallations);
  const response = await elevatedQueryAppInstallations(query,options);
}
```

### queryAppInstallations (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { appInstallations } from '@wix/app-installations';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { appInstallations },
  // Include the auth strategy and host as relevant
});


async function queryAppInstallations(query,options) {
  const response = await myWixClient.appInstallations.queryAppInstallations(query,options);
};
```

---