> 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

# QueryBadges

# Package: activity

# Namespace: Badges

# Method link: https://dev.wix.com/docs/api-reference/crm/members-contacts/members/activity/badges-v4/query-badges.md

## Permission Scopes:
Read Badges: SCOPE.DC-MEMBERS.READ-BADGES

## Introduction

Retrieves a list of badges, given the provided paging, filtering, and sorting.

Query Badges runs with these defaults, which you can override:

- `cursorPaging.limit` is `100`

To learn about working with Query methods, see
[API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language),
[Sorting and Paging](https://dev.wix.com/api/rest/getting-started/pagination),
and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection).

---

## REST API

### Schema

```
 Method: queryBadges
 Description: Retrieves a list of badges, given the provided paging, filtering, and sorting.  Query Badges runs with these defaults, which you can override:  - `cursorPaging.limit` is `100`  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/pagination), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection).
 URL: https://www.wixapis.com/badges/v4/badges/query
 Method: POST
 Method parameters:
   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: Number of items to load. 
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. 
        - 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"}]` 
           - name: fieldName | type: string | description: Name of the field to sort by. 
           - name: order | type: SortOrder | description: Sort order. 
                 - enum: ASC, DESC
 Return type: QueryBadgesResponse
  - name: badges | type: array<Badge> | description: List of badges matching the query criteria. 
     - name: id | type: string | description: Badge GUID. 
     - name: revision | type: string | description: Revision number, which increments by 1 each time the badge is updated. To prevent conflicting changes, the current revision must be passed when updating the badge. 
     - name: title | type: string | description: Badge title displayed on the member's profile. 
     - name: description | type: string | description: Badge description explaining its purpose or criteria for earning it. 
     - name: backgroundColor | type: string | description: Badge background color in hexadecimal RGB format. 
     - name: textColor | type: string | description: Badge text color in hexadecimal RGB format. 
     - name: icon | type: Image | description: Badge icon image.  Any image format is accepted with automatic conversion and resizing handled by the system. SVG format is recommended as it is resolution independent and looks great at any scale. 
        - name: id | type: string | description: [WixMedia](https://support.wix.com/en/article/wix-media-about-the-media-manager) image GUID. If you pass the GUID, you don't need to pass `url`. 
        - name: url | type: string | description: Image URL. Could be any image from the internet. 
        - name: height | type: integer | description: Original image height. 
        - name: width | type: integer | description: Original image width. 
        - name: altText | type: string | description: Image alt text. 
        - name: filename | type: string | description: Image filename. Only applicable when passing `id`. 
     - name: permissionsEnabled | type: boolean | description: Whether the badge grants special permissions to access specific members-only pages.  When `true`, members with this badge receive special permissions. Site owners can configure these permissions in the site dashboard. For more information, see [Creating and Managing Member Badges](https://support.wix.com/en/article/site-members-creating-and-managing-member-badges). 
     - name: slug | type: string | description: URL-friendly slug for the badge, automatically generated from the title.  Generated by converting the title to lowercase, replacing spaces with hyphens, and removing special characters. 
     - name: createdDate | type: string | description: Date and time the badge was created. 
     - name: updatedDate | type: string | description: Date and time the badge was last updated. 
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata for retrieving additional results. 
     - name: count | type: integer | description: Number of items returned in the response. 
     - name: cursors | type: Cursors | description: Offset that was requested. 
        - name: next | type: string | description: Cursor pointing to next page in the list of results. 
        - name: prev | type: string | description: Cursor pointing to previous page in the list of results. 
     - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page. 


```

### Examples

### Query Badges
```curl
curl -X POST \
  'https://www.wixapis.com/badges/v4/badges/query' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "permissionsEnabled": true
      },
      "sort": [
        {
          "fieldName": "title",
          "order": "ASC"
        }
      ],
      "cursorPaging": {
        "limit": 10
      }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.activity.Badges.queryBadges(query)
 Description: Retrieves a list of badges, given the provided paging, filtering, and sorting.  Query Badges runs with these defaults, which you can override:  - `cursorPaging.limit` is `100`  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language), [Sorting and Paging](https://dev.wix.com/api/rest/getting-started/pagination), and [Field Projection](https://dev.wix.com/api/rest/getting-started/field-projection).
 # 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: query | type: BadgeQuery   | 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: Number of items to load. 
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. 
        - 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"}]` 
           - name: fieldName | type: string | description: Name of the field to sort by. 
           - name: order | type: SortOrder | description: Sort order. 
                 - enum: ASC, DESC
 Return type: PROMISE<QueryBadgesResponse>
  - name: badges | type: array<Badge> | description: List of badges matching the query criteria. 
     - name: _id | type: string | description: Badge GUID. 
     - name: revision | type: string | description: Revision number, which increments by 1 each time the badge is updated. To prevent conflicting changes, the current revision must be passed when updating the badge. 
     - name: title | type: string | description: Badge title displayed on the member's profile. 
     - name: description | type: string | description: Badge description explaining its purpose or criteria for earning it. 
     - name: backgroundColor | type: string | description: Badge background color in hexadecimal RGB format. 
     - name: textColor | type: string | description: Badge text color in hexadecimal RGB format. 
     - name: icon | type: string | description: Badge icon image.  Any image format is accepted with automatic conversion and resizing handled by the system. SVG format is recommended as it is resolution independent and looks great at any scale. 
     - name: permissionsEnabled | type: boolean | description: Whether the badge grants special permissions to access specific members-only pages.  When `true`, members with this badge receive special permissions. Site owners can configure these permissions in the site dashboard. For more information, see [Creating and Managing Member Badges](https://support.wix.com/en/article/site-members-creating-and-managing-member-badges). 
     - name: slug | type: string | description: URL-friendly slug for the badge, automatically generated from the title.  Generated by converting the title to lowercase, replacing spaces with hyphens, and removing special characters. 
     - name: _createdDate | type: Date | description: Date and time the badge was created. 
     - name: _updatedDate | type: Date | description: Date and time the badge was last updated. 
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata for retrieving additional results. 
     - name: count | type: integer | description: Number of items returned in the response. 
     - name: cursors | type: Cursors | description: Offset that was requested. 
        - name: next | type: string | description: Cursor pointing to next page in the list of results. 
        - name: prev | type: string | description: Cursor pointing to previous page in the list of results. 
     - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page. 


```

### Examples

### queryBadges
```javascript
import { badgesV2 } from '@wix/members';

async function queryBadges(query) {
  const response = await badgesV2.queryBadges(query);
};
```

### queryBadges (with elevated permissions)
```javascript
import { badgesV2 } from '@wix/members';
import { auth } from '@wix/essentials';

async function myQueryBadgesMethod(query) {
  const elevatedQueryBadges = auth.elevate(badgesV2.queryBadges);
  const response = await elevatedQueryBadges(query);
}
```

### queryBadges (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 { badgesV2 } from '@wix/members';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

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


async function queryBadges(query) {
  const response = await myWixClient.badgesV2.queryBadges(query);
};
```

---