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

# Read the source ledger

> Evidence of every external consultation ever made for the tenancy — who was asked about, when, under what consent, with what outcome. Never the data.

The ledger is the audit trail of consultations: one line per attempt, carrying who was asked about, under what consent, and how it ended. What is **not** on it is the point — no request, no response, no report. The Platform keeps evidence of a call, never a copy of the data, and the table beneath this route has no column that could hold one. [Círculo de Crédito](/lending/circulo) carries the one-authorisation-one-consulta model the ledger evidences.

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy whose consultations these are.
</ParamField>

## Query parameters

<ParamField query="client_id" type="string">
  One Client's consultations only.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  How many lines to serve.
</ParamField>

<ParamField query="before" type="string">
  RFC 3339: serve lines from before this moment — the `next_before` of the previous page, a cursor a caller can read and reason about, because a regulatory export has to be able to say what it asked for.
</ParamField>

## Response

<ResponseField name="entries" type="array" required>
  The lines, newest first. A Tenancy that never consulted answers the empty listing.

  <Expandable title="entry">
    <ResponseField name="id" type="string" required>
      The line's identifier.
    </ResponseField>

    <ResponseField name="source" type="string" required>
      The Source consulted, by its catalogue name.
    </ResponseField>

    <ResponseField name="client_id" type="string" required>
      Your identifier for who was asked about, with `reference` beside it.
    </ResponseField>

    <ResponseField name="consent_artifact_id" type="string">
      Your reference for the borrower's authorisation, with `consent_given_at` and `consent_expires_at` beside it — present where the Source requires consent.
    </ResponseField>

    <ResponseField name="attempt_id" type="string" required>
      The attempt, with `outcome` beside it — the Source's own failure vocabulary, or the success.
    </ResponseField>

    <ResponseField name="source_reference" type="string">
      What the Source called the consultation — the bureau's folio — where it answered one.
    </ResponseField>

    <ResponseField name="cost_unit" type="string" required>
      What the attempt spent, so the ledger reconciles against the Source's own invoice.

      | Value | What it means |
      | - | - |
      | `consulta` | One consultation at the bureau. It appears on their invoice. |
      | `none` | Nothing was spent. |

      A line reads `none` when the Source bills for nothing, and also when the call never left the Platform: the credential you supplied could not be used, so the attempt was refused before anything was sent, or the connection to the Source could not be opened — the name did not resolve, the port refused, or the handshake failed — so nothing was written to it. That line is still here, with its attempt and its outcome, because the refusal is yours to hold; it simply costs nothing and does not count against your daily bound. A failure after the request was written — a reset mid-answer, a deadline while waiting — is priced at the Source's unit, because the Source may have received it and may bill it.
    </ResponseField>

    <ResponseField name="occurred_at" type="string" required>
      RFC 3339: when.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_before" type="string">
  The moment to ask the next page from. Absent on the last one.
</ResponseField>

## Refusals

| Status | Code | When |
| - | - | - |
| `400` | `invalid_query` | The query carries a parameter this route does not read, states one twice, or states one with no value. `before` that is not an RFC 3339 moment is refused here too |
| `400` | `invalid_page_size` | `limit` is below one, above 200, or not a whole number. It is never clamped to a size you did not ask for |
| `403` | `not_permitted_tenant` | The credential authenticates for another Tenancy |
| `429` | `rate_limited` | Your request bounds are exhausted. `Retry-After` says when to return |

<RequestExample>
  ```bash Read theme={null}
  curl "https://api.capcells.com/v1/tenants/$TENANT_ID/source-ledger?limit=5" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" GET "/v1/tenants/$TENANT_ID/source-ledger?limit=5")"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Nothing consulted yet theme={null}
  {
    "entries": []
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.