# Query Cash-Out by Tag

Queries PIX transactions that match a tag (prefix of `transaction_id`). Allows grouping and searching transactions by date, type, or any identifier prefix.

## Endpoint

```
GET /api/external/transactions/tag/:tag
```

## Headers

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| `Authorization` | String | Yes | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Send `camelCase` to receive the response with camelCase keys (e.g., `transactionId`, `endToEndId`, `payerIspb`). Without this header, the response remains `snake_case` as in the example below.see [Authentication](/en/auth-token) |

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag` | String | Yes | Prefix of `transaction_id` for search |

::: tip Tag search examples
- `PIXOUT20260309` -- all outbound PIX transfers on 2026-03-09
- `PIXOUT` -- all outbound PIX transfers
- `PIXIN20260309` -- all PIX receipts on 2026-03-09
:::

## Example

```bash
curl -X GET https://api.monetarie.com/api/external/transactions/tag/PIXOUT20260309 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

## Success Response -- 200

```json
{
  "worked": true,
  "data": [
    {
      "id": "c7f3a8b12d4e4f6a9c1b3e5f7a9b1d3e",
      "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
      "end_to_end_id": "E46026562202603091530abcdef01",
      "external_id": "order-9876",
      "type": "pix",
      "direction": "outbound",
      "status": "settled",
      "amount": 300000,
      "fee_amount": 350,
      "net_amount": 300350,
      "description": "Pagamento fornecedor",
      "counterparty_name": "Joao Silva",
      "recipient_key": "12345678901",
      "payer_document": "46026562000165",
      "recipient_document": "12345678901",
      "payer_ispb": "46026562",
      "payer_bank_name": "Monetarie",
      "created_at": "2026-03-09T15:30:00Z",
      "completed_at": "2026-03-09T15:30:02Z"
    },
    {
      "id": "d8e4b9c23f5a5b7c0d2e4f6a8b0c2e4f",
      "transaction_id": "PIXOUT20260309f6e5d4c3b2a1",
      "end_to_end_id": "E46026562202603091545abcdef02",
      "external_id": null,
      "type": "pix",
      "direction": "outbound",
      "status": "settled",
      "amount": 2500000,
      "fee_amount": 350,
      "net_amount": 2500350,
      "description": "Pagamento serviço",
      "counterparty_name": "Maria Santos",
      "recipient_key": "98765432100",
      "payer_document": "46026562000165",
      "recipient_document": "98765432100",
      "payer_ispb": "46026562",
      "payer_bank_name": "Monetarie",
      "created_at": "2026-03-09T15:45:00Z",
      "completed_at": "2026-03-09T15:45:01Z"
    }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `data` | Array | List of transactions matching the prefix. May come empty (`[]`) when nothing matches - HTTP 200 anyway |

::: info Search scope
The tag search queries **only** the `transactions` table (settled/rejected transactions). PIX OUT in progress (`outbound_requests`, stage 1-2) and unpaid QR Codes (`qrcodes`) **do not appear** in this listing. Use [GET /transactions/:id](/en/pix-cashout-status) or the `pix.payout.confirmed` webhook to track in-progress transactions.
:::

Each object in the array follows the same shape as the "settled transaction" response in [GET /transactions/:id](/en/pix-cashout-status#response-settled-transaction-200). Monetary values in **base units** (÷ 10,000 for BRL). Fields `payer_document`, `recipient_document`, `payer_ispb`, and `payer_bank_name` come from the transaction metadata and may be `null` on old rows. For rejected transactions, the response includes `reason_code` and `reason_description` (in English).

::: warning Result limit
The tag search returns at most **50 transactions** per request, ordered by `started_at` desc (most recent first). There is no pagination - use more specific prefixes (e.g., `PIXOUT20260309` for a full day, or `PIXOUT2026030915` for an hourly window) to refine.
:::

## Empty Response -- 200

When no transactions match the provided prefix:

```json
{
  "worked": true,
  "data": []
}
```