# /query Endpoint

ESS supports an [authorization mechanism based on Access Requests and Grants](/security/authorization/access-requests-grants.md).

ESS serializes the Access Requests and Grants as [Verifiable Credentials (VCs)](/reference/glossary.md#verifiable-credential) The query endpoint provides an optimized mechanism to search and filter these VCs.

## /query Endpoint

The ESS [Access Grant Service](/ess/2.3/services/service-access-grant.md) provides an endpoint with the following URL:

```jsdoc
https://vc.<ESS DOMAIN>/query
```

{% hint style="info" %}
**Note**\
Access to the **`/query`** endpoint requires users to be authenticated. The endpoint supports the use of either [Solid-OpenID Connect (OIDC) access token](/ess/2.3/services/service-oidc.md) or [UMA token](/ess/2.3/services/service-uma.md).
{% endhint %}

To query for Access Requests or Grants, clients can send a request to the endpoint:

<table data-header-hidden><thead><tr><th width="162.37005615234375"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><strong><code>GET</code></strong></td></tr><tr><td>Endpoint</td><td><strong><code>https://vc.&#x3C;ESS DOMAIN>/query</code></strong></td></tr><tr><td>Query Parameters</td><td>Parameters that control which results are returned. See <a href="#input-query-parameters">Input: Query Parameters</a> for details.</td></tr></tbody></table>

### Behavior

The ESS **`/query`** endpoint adds support for retrieving access credentials based on a defined set of filters. Please see [Input: Query Parameters](#input-query-parameters) for details.

The results are be available via a pageable interface. Clients can use **`Link`** headers in the response to navigate through the result pages. The query result body consists of a JSON object that lists access credentials formatted as VCs . Please see [Output: Query Response](#output-query-response) for details.

## Input: Query Parameters

<table data-header-hidden><thead><tr><th width="169.46881103515625"></th><th></th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td>One of <strong><code>SolidAccessRequest</code></strong>, <strong><code>SolidAccessGrant</code></strong>, <strong><code>SolidAccessDenial</code></strong></td></tr><tr><td><strong><code>status</code></strong></td><td>One of <strong><code>Pending</code></strong>, <strong><code>Denied</code></strong>, <strong><code>Granted</code></strong>, <strong><code>Canceled</code></strong>, <strong><code>Expired</code></strong>, <strong><code>Active</code></strong>, <strong><code>Revoked</code></strong>. Please see <a href="#status-values">Status values</a> for details.</td></tr><tr><td><strong><code>fromAgent</code></strong></td><td>The WebID of the creator of the access credential.</td></tr><tr><td><strong><code>toAgent</code></strong></td><td>The WebID of the recipient of the access credential.</td></tr><tr><td><strong><code>resource</code></strong></td><td>The URL of a storage location specified in the access credential.</td></tr><tr><td><strong><code>purpose</code></strong></td><td>The URL of a purpose identifier specified in the access credential.</td></tr><tr><td><strong><code>issuedWithin</code></strong></td><td>One of <strong><code>P1D</code></strong> (one day), <strong><code>P7D</code></strong> (one week) <strong><code>P1M</code></strong> (one month) or <strong><code>P3M</code></strong> (three months).<br>This parameter will limit the results to those that were issued within the specified time period.</td></tr><tr><td><strong><code>revokedWithin</code></strong></td><td>One of <strong><code>P1D</code></strong> (one day), <strong><code>P7D</code></strong> (one week) <strong><code>P1M</code></strong> (one month) or <strong><code>P3M</code></strong> (three months).<br>This parameter is only relevant when <strong><code>status</code></strong> is <strong><code>Revoked</code></strong> or <strong><code>Canceled</code></strong>. This will limit the results to those that were revoked within the specified time period.</td></tr><tr><td><strong><code>pageSize</code></strong></td><td>This controls the maximum number of results in a page of results. By default, this value is 20. It may not exceed 100.</td></tr><tr><td><strong><code>page</code></strong></td><td>This value is an opaque cursor used to navigate through result pages. A client should make use of this value when consuming <strong><code>Link</code></strong> headers in a response but should not need to set this value independently.</td></tr></tbody></table>

### Status values

**`Active`**

This status value will list Access Grants that have not expired and have not been revoked. This value is only relevant when **`type`** is **`SolidAccessGrant`** .

**`Expired`**

This status value will list Access Grants that have expired. This value is only relevant when **`type`** is **`SolidAccessGrant`** .

**`Revoked`**

This status value will list Access Grants that have been revoked. This value is only relevant when **`type`** is **`SolidAccessGrant`** .

**`Pending`**

This status value will list Access Requests that do not have a corresponding Access Grant or Access Denial. This value is only relevant when **`type`** is **`SolidAccessRequest`** .

**`Granted`**

This status value will list Access Requests that have a corresponding Access Grant. This value is only relevant when **`type`** is **`SolidAccessRequest`** .

**`Denied`**

This status value will list Access Requests that have a corresponding Access Denial. This also can be used with Access Denial types. This value is relevant when the **`type`** is either **`SolidAccessRequest`** or **`SolidAccessDenial`** .

**`Canceled`**

This status value will list Access Requests that have been revoked (i.e. canceled). This value is only relevant when **`type`** is **`SolidAccessRequest`** .

## Output: Query Response

The **`/query`** endpoint returns a JSON object containing an individual page of results as part of a pageable interface. By default, each page of results will contain up to 20 items.

```json
{
  "items": [
    { // Matching access credential VC },
    { // Matching access credential VC },
    ...
  ]
}
```

When there are multiple pages of results, **`Link`** headers will point to the **`first`** , **`last`** , **`prev`** and **`next`** page, as appropriate. The first page, for example, will not include a **`prev`** link.

Example **`Link`** headers are included below:

```none
Link: </query?type=SolidAccessGrant&status=Active&page=323904ad>; rel="first"
Link: </query?type=SolidAccessGrant&status=Active&page=3d224607>; rel="prev"
Link: </query?type=SolidAccessGrant&status=Active&page=6af7d740>; rel="next"
Link: </query?type=SolidAccessGrant&status=Active&page=35faea55>; rel="last"
```

The **`page`** parameter is used to navigate through an ordered list of pages. Client applications should treat this value as opaque.

## Examples

These examples describe some common queries that application developers may use. In each example, the URL is formatted across multiple lines to improve readability. Please note that all URI parameters are URL-encoded; this is especially important for URIs that contain hash fragments, i.e. sections beginning with the character **`#`** .

### Example 1

The following query searches for all pending Access Requests from the last week, targeting a particular user, such as the current user of an application. The results of this query may represent the list of outstanding requests that a user should either approve or reject.

```none
/query?type=SolidAccessRequest
    &status=Pending
    &issuedWithin=P7D
    &toAgent=https%3A%2F%2Fid.example%2Fusername
```

### Example 2

The following query searches for all Access Grants that a particular user has issued in the last month. This might allow a user to understand who has been granted access to their Storage to decide if access needs to be changed for anyone.

```none
/query?type=SolidAccessGrant
    &status=Active
    &issuedWithin=P1M
    &fromAgent=https%3A%2F%2Fid.example%2Fusername
```

### Example 3

The following query searches for all Access Requests made by a particular user in the last three months that have been denied.

```none
/query?type=SolidAccessRequest
    &status=Denied
    &issuedWithin=P3M
    &fromAgent=https%3A%2F%2Fid.example%2Fusername
```

### Example 4

The following query searches for all Access Grants that a user has received from others.

```
/query?type=SolidAccessGrant
    &status=Active
    &toAgent=https%3A%2F%2Fid.example%2Fusername
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inrupt.com/ess/2.3/services/service-access-grant/service-access-grant-query.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.