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

# Custom Metrics by CUIT

> Incremental CBU/CVU metrics over a custom calendar lookback (1–180 days) — billable per request when priced.

## Overview

Returns **custom incremental metrics** for a calendar lookback ending on a reference date: deltas, % change, daily variance, and acceleration when enough history exists. **One billable request** per successful call when priced.

## Endpoint

```
GET https://api.gu1.ai/api/integration-services/ar_gueno_holder_intelligence_service/cuits/{cuit}/metrics
```

## Path parameters

<ParamField path="cuit" type="string" required>
  Argentina CUIT/CUIL — **11 digits**, no dashes.
</ParamField>

## Query parameters

<ParamField query="lookback" type="integer" required>
  Calendar days in the window (**1–180**, inclusive).
</ParamField>

<ParamField query="date" type="string">
  Optional. Inclusive window end (`YYYY-MM-DD`). Defaults to latest corpus date when omitted.
</ParamField>

## Success response (HTTP 200)

<ResponseField name="success" type="boolean">
  `true`
</ResponseField>

<ResponseField name="data.complete" type="boolean">
  Always `true` on success.
</ResponseField>

<ResponseField name="data.lookbackDays" type="number">
  Echo of requested lookback.
</ResponseField>

<ResponseField name="data.referenceDate" type="string">
  Inclusive window end (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="data.windowStart" type="string">
  Window start date (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="data.windowEnd" type="string">
  Window end date (`YYYY-MM-DD`), same as reference date.
</ResponseField>

<ResponseField name="data.metrics" type="object">
  * `cbuTotalStart`, `cbuTotalEnd`, `cvuTotalStart`, `cvuTotalEnd` (numbers)
  * `cbuDelta`, `cvuDelta` (numbers)
  * `cbuPctChange`, `cvuPctChange` (number | null)
  * `daysWithChanges` (number)
  * `cbuDailyDeltaVariance`, `cvuDailyDeltaVariance` (number | null)
  * `cbuAcceleration`, `cvuAcceleration`, `totalAcceleration` (number | null)
  * `accelerationAvailable` (boolean) — when `false`, acceleration fields are `null`
</ResponseField>

## Incomplete window (HTTP 422)

When incremental state cannot satisfy the lookback, the API returns `success: false` with a partial `data` payload:

| `error.code`           | Meaning                                                                       |
| ---------------------- | ----------------------------------------------------------------------------- |
| `INCOMPLETE_WINDOW`    | Missing daily snapshots in the requested range (`missingDates` may be listed) |
| `NO_INCREMENTAL_STATE` | No incremental history for this CUIT                                          |

Example:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INCOMPLETE_WINDOW",
    "message": "Incremental window incomplete for the requested lookback"
  },
  "data": {
    "integrationCode": "ar_gueno_holder_intelligence_service",
    "cuit": "20384648798",
    "complete": false,
    "error": "incomplete_window",
    "lookbackDays": 30,
    "referenceDate": "2026-06-24",
    "windowStart": "2026-05-26",
    "windowEnd": "2026-06-24",
    "missingDates": ["2026-05-27"]
  }
}
```

## Other errors

| HTTP | `error.code`           | When                                |
| ---- | ---------------------- | ----------------------------------- |
| 400  | `INVALID_LOOKBACK`     | `lookback` missing or outside 1–180 |
| 400  | `INVALID_DATE`         | Malformed `date`                    |
| 404  | `CUIT_NOT_FOUND`       | CUIT not in corpus                  |
| 402  | `INSUFFICIENT_BALANCE` | Credits or pack exhausted           |
| 503  | `SERVICE_UNAVAILABLE`  | Holder backend unavailable          |
| 500  | `INTERNAL_ERROR`       | Unexpected error                    |

## Example

```bash theme={null}
curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.gu1.ai/api/integration-services/ar_gueno_holder_intelligence_service/cuits/20384648798/metrics?lookback=7&date=2026-06-24"
```

```json theme={null}
{
  "success": true,
  "data": {
    "integrationCode": "ar_gueno_holder_intelligence_service",
    "cuit": "20384648798",
    "complete": true,
    "referenceDate": "2026-06-24",
    "lookbackDays": 7,
    "windowStart": "2026-06-18",
    "windowEnd": "2026-06-24",
    "metrics": {
      "cbuTotalStart": 2,
      "cbuTotalEnd": 3,
      "cvuTotalStart": 1,
      "cvuTotalEnd": 2,
      "cbuDelta": 1,
      "cvuDelta": 1,
      "cbuPctChange": 50.0,
      "cvuPctChange": 100.0,
      "daysWithChanges": 2,
      "cbuDailyDeltaVariance": 0.1,
      "cvuDailyDeltaVariance": 0.05,
      "cbuAcceleration": 0.5,
      "cvuAcceleration": 0.3,
      "totalAcceleration": 0.8,
      "accelerationAvailable": true
    }
  }
}
```

## Rules engine

Metrics conditions require **`holderIntelligenceLookbackDays`** (1–180) on the rule condition.

| API / block field           | Rule field (examples)                                     |
| --------------------------- | --------------------------------------------------------- |
| `metrics.cbuAcceleration`   | `services.holder_intelligence.metrics.cbu_acceleration`   |
| `metrics.cbuPctChange`      | `services.holder_intelligence.metrics.cbu_pct_change`     |
| `metrics.totalAcceleration` | `services.holder_intelligence.metrics.total_acceleration` |
| `complete`                  | `services.holder_intelligence.metrics.complete`           |

**Transaction rules:** the reference date defaults to **`transactedAt`** converted to Argentina calendar date unless you set `holderIntelligenceReferenceDateField` on the condition.

See [Rules conditions](/en/api-reference/rules/conditions).