> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters API

> Retrieve filtered records from a Blnk Core instance via JSON filters through Blnk Cloud.

export const CtaCallout = props => {
  const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
  const handleCtaClick = () => {
    if (typeof window === "undefined" || !trackingEvent) {
      return;
    }
    try {
      window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
        detail: {
          name: trackingEvent,
          href
        }
      }));
    } catch {}
    try {
      window.posthog?.capture?.(trackingEvent, {
        href
      });
    } catch {}
    const gaPayload = {
      cta_href: href
    };
    try {
      window.gtag?.("event", trackingEvent, gaPayload);
    } catch {}
    try {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: trackingEvent,
        ...gaPayload
      });
    } catch {}
  };
  const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
  const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
  const linkRel = isExternal ? rel : undefined;
  return <section className="cta-callout not-prose relative my-8 w-full min-w-0 overflow-hidden rounded-xl border border-zinc-200 p-5 dark:border-white/10">
      <div className="cta-callout-noise" aria-hidden="true" />
      <div className="cta-callout-layout">
        {title ? <div className="cta-callout-title-row">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28" width="14" height="14" className="cta-callout-icon shrink-0 text-zinc-800 dark:text-zinc-200" aria-hidden="true">
              <g fill="none" fillRule="nonzero">
                <path d="M28 0v28H0V0h28ZM14.691833333333335 27.134333333333334l-0.012833333333333334 0.0023333333333333335 -0.08283333333333333 0.04083333333333334 -0.023333333333333334 0.004666666666666667 -0.016333333333333335 -0.004666666666666667 -0.08283333333333333 -0.04083333333333334c-0.011666666666666667 -0.004666666666666667 -0.022166666666666668 -0.0011666666666666668 -0.028000000000000004 0.005833333333333334l-0.004666666666666667 0.011666666666666667 -0.019833333333333335 0.49933333333333335 0.005833333333333334 0.023333333333333334 0.011666666666666667 0.015166666666666667 0.12133333333333333 0.08633333333333333 0.0175 0.004666666666666667 0.014000000000000002 -0.004666666666666667 0.12133333333333333 -0.08633333333333333 0.014000000000000002 -0.018666666666666668 0.004666666666666667 -0.019833333333333335 -0.019833333333333335 -0.4981666666666667c-0.0023333333333333335 -0.011666666666666667 -0.0105 -0.019833333333333335 -0.019833333333333335 -0.021Zm0.3091666666666667 -0.13183333333333336 -0.015166666666666667 0.0023333333333333335 -0.21583333333333335 0.1085 -0.011666666666666667 0.011666666666666667 -0.0035000000000000005 0.012833333333333334 0.021 0.5016666666666667 0.005833333333333334 0.014000000000000002 0.009333333333333334 0.008166666666666668 0.23450000000000004 0.1085c0.014000000000000002 0.004666666666666667 0.026833333333333334 0 0.03383333333333334 -0.009333333333333334l0.004666666666666667 -0.016333333333333335 -0.03966666666666667 -0.7163333333333334c-0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.023333333333333334 -0.023333333333333334 -0.025666666666666667Zm-0.8341666666666667 0.0023333333333333335a0.026833333333333334 0.026833333333334334 0 0 0 -0.0315 0.007000000000000001l-0.007000000000000001 0.016333333333333335 -0.03966666666666667 0.7163333333333334c0 0.014000000000000002 0.008166666666666668 0.023333333333333334 0.019833333333333335 0.028000000000000004l0.0175 -0.0023333333333333335 0.23450000000000004 -0.1085 0.011666666666666667 -0.009333333333333334 0.004666666666666667 -0.012833333333333334 0.019833333333333335 -0.5016666666666667 -0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.011666666666666667 -0.21466666666666667 -0.10733333333333334Z" strokeWidth="1.1667" />
                <path fill="currentColor" d="M14 2.916666666666667A1.75 1.75 0 0 1 15.750000000000002 4.666666666666667v6.302333333333334L21.207666666666668 7.816666666666667a1.75 1.75 0 0 1 1.75 3.031L17.5 14l5.457666666666667 3.151166666666667a1.75 1.75 0 0 1 -1.75 3.031l-5.457666666666667 -3.1500000000000004V23.333333333333336a1.75 1.75 0 0 1 -3.5 0v-6.302333333333334L6.792333333333334 20.183333333333337a1.75 1.75 0 1 1 -1.75 -3.031L10.5 14 5.042333333333334 10.848833333333333a1.75 1.75 0 0 1 1.75 -3.031l5.457666666666667 3.1500000000000004V4.666666666666667A1.75 1.75 0 0 1 14 2.916666666666667Z" strokeWidth="1.1667" />
              </g>
            </svg>
            <p className="cta-callout-title min-w-0 font-semibold text-zinc-800 dark:text-zinc-200">
              {title}
            </p>
          </div> : null}
        <div className={`cta-callout-body text-sm leading-normal text-zinc-800 dark:text-zinc-200${title ? " cta-callout-body--indented" : ""}`}>
          {children}
        </div>
        <a href={href} target={target} rel={linkRel} onClick={handleCtaClick} data-docs-cta={trackingEvent || undefined} className="cta-callout-button inline-flex items-center justify-center gap-1 rounded-full bg-white px-3 py-1.5 text-sm font-semibold transition hover:bg-zinc-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 dark:bg-white dark:hover:bg-zinc-200">
          {buttonLabel}
          <span className="cta-callout-button-arrow" aria-hidden="true">
            →
          </span>
        </a>
      </div>
    </section>;
};

The Filters API lets you retrieve filtered records from a Blnk Core instance through Blnk Cloud. Send a POST request with a JSON filter body to query instance Postgres directly.

<Note>
  Filter endpoints are registered at the Cloud API root (for example, `/transactions/filter`), not under `/data/` or `/proxy/`. For a step-by-step guide, see [Filtering data](/cloud/proxy/filters-api).
</Note>

***

### Request structure

<RequestExample>
  ```bash cURL wrap theme={"system"}
  curl -X POST 'https://api.cloud.blnkfinance.com/transactions/filter?instance_id=YOUR_INSTANCE_ID&page=1&pageSize=20' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
      "filters": [
        { "field": "status", "operator": "eq", "value": "APPLIED" },
        { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
      ]
    }'
  ```
</RequestExample>

<ParamField header="Authorization" type="string" required>
  Bearer token for an API key or OAuth access token. Requires the `data:read` scope. Create credentials with the `data:read` scope in [API keys](/cloud/auth/api-keys) or [OAuth clients](/cloud/auth/oauth).
</ParamField>

<ParamField query="instance_id" type="string" required>
  Unique identifier of the Blnk Core instance to query. Required on every Filters API request.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for paginated results.
</ParamField>

<ParamField query="pageSize" type="integer">
  Number of records per page. Defaults vary by resource (see endpoints table below).
</ParamField>

<ParamField body="filters" type="array" required>
  Array of filter objects. Each object requires `field` and `operator`, and optionally `value` or `values`.

  Examples:

  * `[{"field": "status", "operator": "eq", "value": "APPLIED"}]` — exact match
  * `[{"field": "currency", "operator": "in", "values": ["USD", "EUR"]}]` — multiple values
  * `[{"field": "created_at", "operator": "between", "values": ["2025-01-01T00:00:00Z", "2025-01-31T23:59:59Z"]}]`
</ParamField>

***

### Endpoints

All paths are relative to `https://api.cloud.blnkfinance.com`.

| Method | Path                     | Default pageSize |
| ------ | ------------------------ | ---------------- |
| POST   | `/ledger/filter`         | 30               |
| POST   | `/balances/filter`       | 20               |
| POST   | `/transactions/filter`   | 20               |
| POST   | `/identities/filter`     | 20               |
| POST   | `/reconciliation/filter` | 20               |

<Warning>
  The ledgers endpoint uses `/ledger/filter` (singular), not `/ledgers/filter`.
</Warning>

<Tip>
  For supported operators and filterable fields, see [Filtering data](/cloud/proxy/filters-api).
</Tip>

***

### Response structure

<ResponseExample>
  ```json Success theme={"system"}
  {
    "data": [
      {
        "transaction_id": "txn_c4e70eb8-e4d6-4e04-a2e2-92a43b969e0c",
        "amount": 100.50,
        "currency": "USD",
        "status": "APPLIED",
        "created_at": "2025-01-15T10:00:00.000000000Z"
      }
    ],
    "total": 12,
    "stats": {},
    "total_is_estimate": false,
    "total_source": "exact"
  }
  ```
</ResponseExample>

<ResponseField name="data" type="array" required>
  Array of matching records. Structure varies by resource type.
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of matching records.
</ResponseField>

<ResponseField name="stats" type="object">
  Aggregate statistics for the filtered result set. Present on balances, transactions, identities, and reconciliations.
</ResponseField>

<ResponseField name="total_is_estimate" type="boolean">
  Transactions only. When `true`, the `total` value is an estimate rather than an exact count.
</ResponseField>

<ResponseField name="total_source" type="string">
  Transactions only. Indicates how the total was computed (for example, `"exact"` or `"estimate"`).
</ResponseField>

<Info>
  The Cloud Filters API accepts `{ "filters": [...] }` in the body with pagination via query parameters.

  This differs from the self-hosted Core Filter API documented in [Search via DB](/reference/search-db), which uses `limit`, `offset`, `sort_by`, and `include_count` in the body and returns `total_count`.
</Info>

***

## Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

<CtaCallout title="Need help with your product?" href="https://blnkfinance.com/contact/us?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=home%2Finstall" buttonLabel="Speak with us" trackingEvent="clicked_pro_support">
  Get dedicated support for architecture reviews, integration planning, ledger workflows, and production deployment.
</CtaCallout>