> For the complete documentation index, see [llms.txt](https://carpool.gitbook.io/carpool/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://carpool.gitbook.io/carpool/api-reference/filters/instruction-filters.md).

# Instruction Filters

## Overview

Several of Carpool's instruction queries accept a filter object in the POST body. This is an abstraction on top of Elasticsearch and is made to help users perform powerful aggregations and searches. Below you can find all possible filters for i**nstruction queries**

## **Instruction Filters**

<details>

<summary>📒 INSTRUCTION_ACCOUNT </summary>

#### Description:

Filter for instructions that contain a specific account

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* accountPubKey<mark style="color:red;">\*</mark>
* accountName

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_ACCOUNT",
    "accountPubKey": "string",
    "accountName": "string" // A specific account in an instruction's args (via IDL). Leave blank to match any account in the instruction.
}
```

#### Example

```json
"filter": {
    "type": "INSTRUCTION_ACCOUNT",
    "accountPubKey": "8mpTNU6vpLSD9mWx4BQt2S6sz2yP39ZhQ9TuMXY4MgUz",
    "accountName": "authority"
}
```

</details>

<details>

<summary>📛 INSTRUCTION_NAME</summary>

#### Description:

Filter for instructions that contain a specific instruction name

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* instructionName<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_NAME",
    "instructionName": "string"
}
```

#### Example

```json
"filter": {
    "type": "INSTRUCTION_NAME",
    "instructionName": "depositFunds"
}
```

</details>

<details>

<summary>🪵 INSTRUCTION_LOGS</summary>

#### Description:

Filter for instructions that contain the searched text in the their logs

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* searchText<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_LOGS",
    "searchText": "string"
}
```

#### Example

```json
"filter": {
    "type": "INSTRUCTION_LOGS",
    "searchText": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
}
```

</details>

<details>

<summary>1️⃣ INSTRUCTION_ARG_NUMERIC</summary>

#### Description:

Search for instructions with specific numeric arguments present

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* path<mark style="color:red;">\*</mark>
* range<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_ARG_NUMERIC",
    "path": "string", // Dot-delimited for nested fields
    "range": NumericRange
}
```

#### NumericRange type

```typescript
// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;
```

#### Example - 1

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_ARG_NUMERIC",
    "path": "args.clientOrderId",
    "range": {
        "gte": 2
    }
}
```

{% endcode %}

#### Example - 2

```json
"filter": {
    "type": "INSTRUCTION_ARG_NUMERIC",
    "path": "data.creators.percentageShare",
    "range": {
        "eq": 100
    }
}
```

</details>

<details>

<summary>💭 INSTRUCTION_ARG_KEYWORD</summary>

#### Description:

Search for instructions with specific string keyword arguments present

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* path<mark style="color:red;">\*</mark>
* value<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_ARG_KEYWORD",
    "path": "string", // Dot-delimited for nested fields
    "value": "string"
}
```

#### Example - 1

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_ARG_KEYWORD",
    "path": "newAuthority",
    "value": "ggkMbwPY67ctc1UhETtfvAxzHqV3NJX1ESpPoMhUni3"
}
```

{% endcode %}

#### Example - 2

```json
"filter": {
    "type": "INSTRUCTION_ARG_KEYWORD",
    "path": "data.creators.address",
    "value": "HrBfXpVbojurL5sUJGV7N2WuQDrvSKRFAiwFgpNHHxD3"
}
```

</details>

<details>

<summary>✅ INSTRUCTION_ARG_EXISTS</summary>

#### Description:

Search for instructions where a specific argument key is present

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* path<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_ARG_EXISTS",
    "path": "string" // Dot-delimited for nested fields
}
```

#### Example

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_ARG_EXISTS",
    "path": "data.creators.address"
}
```

{% endcode %}

</details>

<details>

<summary>⚠️ INSTRUCTION_ERROR_CODE</summary>

#### Description:

Search for failed instructions where an errorCode is present. **Note -** you must have "failures" set to **true** within your query object in your POST body

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* errorCode

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_ERROR_CODE",
    "errorCode": number // search all if left blank
}
```

#### Example

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_ERROR_CODE",
    "errorCode": 7
}
```

{% endcode %}

</details>

<details>

<summary>☎️ INSTRUCTION_CPI_INVOKER</summary>

#### Description:

Search for instructions where a CPI has been invoked

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* cpiProgramId

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_CPI_INVOKER",
    "cpiProgramId": "string" // Not set means ANY CPI (you should negate this to remove CPIs).
}
```

#### Example

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_CPI_INVOKER"
}
```

{% endcode %}

</details>

<details>

<summary>💰 INSTRUCTION_BALANCES</summary>

#### Description:

Search for instructions that match a specified balance or range.

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* accountPubKey
* token
* delta

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_BALANCES",
    "accountPubKey": "string", // Scope balance changes to a particular account.
    "token": { // Not setting token will search lamports instead.
        "mint": "string", // The specific token mint
        "owner": "string" // The token account owner
    },
    "delta": NumericRange
}
```

#### NumericRange Type

```typescript
// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;
```

#### Example - 1

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_BALANCES",
    "accountPubKey": "ykjAirXX9GxX8FF9RdhvfqX5v2cKqABrpafhjkASoaa"
}
```

{% endcode %}

#### Example - 2&#x20;

This example can be used to find an instance(s) where a particular accountPubKey paid an exact amount of SOL.&#x20;

```json
"filter": {
    "type": "INSTRUCTION_BALANCES",
    "accountPubKey": "ykjAirXX9GxX8FF9RdhvfqX5v2cKqABrpafhjkASoaa", 
    "delta": {
        "eq": -525478160
    }
}
```

</details>

<details>

<summary>📅 INSTRUCTION_EVENT_EXISTS</summary>

#### Description:

Search for instructions where a specific Anchor event name is present

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* eventName<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "path": "string" // Dot-delimited for nested fields
}
```

#### Example

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "path": "MovieCreationEvent"
}
```

{% endcode %}

</details>

<details>

<summary>2️⃣ INSTRUCTION_EVENT_DATA_NUMERIC</summary>

#### Description:

Search for instructions with specific event numeric values present

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* eventName<mark style="color:red;">\*</mark>
* path<mark style="color:red;">\*</mark>
* range<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_EVENT_DATA_NUMERIC",
    "eventName": "string",
    "path": "string", // Dot-delimited for nested fields
    "range": NumericRange
}
```

#### NumericRange type

```typescript
// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;
```

#### Example - 1

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_EVENT_DATA_NUMERIC",
    "eventName": "CounterEvent",
    "path": "data",
    "range": {
        "eq": 1
    }
}
```

{% endcode %}

#### Example - 2

```json
"filter": {
    "type": "INSTRUCTION_EVENT_DATA_NUMERIC",
    "eventName": "CounterEvent",
    "path": "data",
    "range": {
        "gte": 10
    }
}
```

</details>

<details>

<summary>🔤 INSTRUCTION_EVENT_DATA_KEYWORD</summary>

#### Description:

Search for instructions with specific string keywords present in the events

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* eventName<mark style="color:red;">\*</mark>
* path<mark style="color:red;">\*</mark>
* value<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_EVENT_DATA_KEYWORD",
    "eventName": "string",
    "path": "string", // Dot-delimited for nested fields
    "value": "string"
}
```

#### Example -&#x20;

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_EVENT_DATA_KEYWORD",
    "eventName": "MovieCreationEvent",
    "path": "title",
    "value": "Shawshank Redemption"
}
```

{% endcode %}

</details>

<details>

<summary>📊 INSTRUCTION_EVENT_DATA_EXISTS</summary>

#### Description:

Search for instructions where a specific Anchor event data fields is present

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* eventName<mark style="color:red;">\*</mark>
* path<mark style="color:red;">\*</mark>

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "eventName": "string",
    "path": "string" // Dot-delimited for nested fields
}
```

#### Example

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_EVENT_EXISTS",
    "eventName": "MovieCreationEvent",
    "path": "title"
}
```

{% endcode %}

</details>

<details>

<summary>🔁 INSTRUCTION_TRANSFERS</summary>

#### Description:

Search for instructions with specific transfers done on an instruction level

**Schema fields:**

* type<mark style="color:red;">\*</mark>
* from
* to
* fromOwner
* toOwner
* mint
* amount

#### Schema

```json
"filter": {
    "type": "INSTRUCTION_TRANSFERS",
    "from": "string",
    "to": "string",
    "fromOwner": "string", // Only different for Token transfers.
    "toOwner": "string", // Only different for Token transfers.
    "mint": "string", // Only applies to Token transfers - empty for SOL.
    "amount": NumericRange // The amount transferred.
}
```

#### NumericRange Type

```typescript
// Either an equality check, or GTE/LTE range, one of which must be set.
export type NumericRange = XOR<XOR<{
  gte: number;
  lte?: number;
}, {
  gte?: number;
  lte: number;
}>, { eq: number }>;
```

#### Example - 1

{% code fullWidth="true" %}

```json
"filter": {
    "type": "INSTRUCTION_TRANSFERS"
}
```

{% endcode %}

#### Example - 2

```json
"filter": {
    "type": "INSTRUCTION_TRANSFERS",
    "from": "",
    "to": "Cy8WZzQC8QuGPBAFR3XUprJL4G6xYHir1CT3d17vGA4n",
    "fromOwner": "",
    "toOwner": "FyHDZjeK8xqcCidCDwPMLpomRmQT8HrM5dD1U5yFKJv3",
    "mint": "Fx17xv1KJipenEMRrPsX3soJujReNTDN7d4Tqw55q9Zf",
    "amount": {
        "gte": 50
    }
}
```

</details>

## Combining Filters

It is important to note that you can also combine any of the above filters within a single query. You can return results based on an **AND** or **OR** condition.

### AND

#### Schema

```json
"filter": {
    "and": [
        {
            "type": "FILTER_TYPE",
            ...
        },
        {
            "type": "FILTER_TYPE",
            ...
        },
        ...
    ]
}
```

#### Example

```json
"filter": {
    "and": [
        {
            "type": "INSTRUCTION_ARG_EXISTS",
            "path": "data.creators.address"
        },
        {
            "type": "INSTRUCTION_ARG_NUMERIC",
            "path": "data.creators.percentageShare",
            "range": {
                "eq": 100
            }
        }
    ]
}
```

### OR

#### Schema

```json
"filter": {
    "or": [
        {
            "type": "FILTER_TYPE",
            ...
        },
        {
            "type": "FILTER_TYPE",
            ...
        },
        ...
    ]
}
```

#### Example

```json
"filter": {
    "or": [
        {
            "type": "INSTRUCTION_ARG_EXISTS",
            "path": "data.creators.address"
        },
        {
            "type": "INSTRUCTION_ARG_NUMERIC",
            "path": "data.creators.percentageShare",
            "range": {
                "eq": 100
            }
        }
    ]
}
```

## Negating Filters

You can also negate filters if you'd like to look for all instructions that do **not** match the filter criteria. To negate, simply add  `"negate": true` to the top level of the filter.

#### Example

```json
"filter": {
    "type": "INSTRUCTION_ARG_EXISTS",
    "path": "data.creators.address",
    "negate": true
}
```