> ## 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 a facility
> Read a grant together with what has been drawn from it and what is left.
This call answers a Facility as it was created, and the two figures that move: what has been drawn under it, and what remains.
Headroom is the grant's amount minus the sum of the original principals of every Loan ever issued under it, whatever each Loan's later state.
Headroom only ever decreases. Repayment, prepayment, reversal, cancellation, write-off and acceleration restore nothing. Freeing capacity is a new Decision and a new Facility, not an automatic effect of anything that happens to a Loan.
## Path parameters
The Tenancy whose grant is read. Another Tenancy's path answers `403`.
The grant's identifier, as the creation answered it.
## Response
Every field the creation answers, and two more.
The sum of the original principals of every Loan ever issued under this grant, as `minor_units` and `currency`.
The amount minus what was drawn. This is the figure an issuance is held against.
On a line, the day `drawn` and `headroom` are as of. Absent on a one-draw grant, whose figures name no day.
On a line another line renewed, that line. Absent otherwise.
## A worked remainder
A grant of MXN 10,000.00 with Loans of MXN 3,000.00 and MXN 2,000.00 issued under it answers `drawn` of `500000` and `headroom` of `500000`.
Cancel either Loan and the two figures do not move. Repay both in full and they do not move. The grant records what was drawn, and it has no opinion about what became of it.
## A line's remainder
A line answers the same two figures differently, and three more fields beside them. `drawn` is the principal still outstanding on its Loans — and on the Loans of every line it superseded — as of `on`, the day the read falls on in the zone the line froze. `headroom` is the amount less that, never below zero. Repay MXN 1,500.00 of a MXN 4,000.00 draw on a MXN 10,000.00 line and `headroom` reads `750000` from the receipt's value date; reverse the receipt and it reads `600000` again.
A line another line superseded carries `superseded_by`, and its `headroom` reads zero from the day its successor opens.
## Why the read and the issuance cannot disagree
The Platform derives this figure once. The Facility asks the loan domain how much has been drawn under it, and issuance holds a new principal against the same query over the same rows — so the answer here is the answer an issuance would get, taken at the same moment.
What the read cannot promise is that the figure survives the next request. Two issuances against one grant are serialised against each other; a read is not, and a Loan issued between your read and your issuance moves the remainder. Issuance decides again, under the Client's lock, and that decision is the one that binds.
## Refusals
This route reads no query parameter and takes no body.
| Status | When |
| - | - |
| `400` | The URL carries a query parameter, which this route does not read |
| `403` | The key authenticates for another Tenancy |
| `404` | No such grant, or it belongs to another Tenancy |
Those two are the same `404`, which is what keeps them indistinguishable from outside. An identifier the Platform cannot even read as one answers the same way. A read-scoped key is enough.
```bash Read theme={null}
curl https://api.capcells.com/v1/tenants/capyplazo/facilities/3a156e45-e3df-4dc1-9a80-8dca3e58a0cc \
-H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" GET /v1/tenants/capyplazo/facilities/3a156e45-e3df-4dc1-9a80-8dca3e58a0cc)"
```
```json 200 theme={null}
{
"id": "3a156e45-e3df-4dc1-9a80-8dca3e58a0cc",
"client_id": "client-alonso",
"configuration_id": "9ae76f4e-2eb4-43ce-831c-f3b1aa7b5dd6",
"decided_version": 1,
"decision_id": "4e19e899-fa40-4047-bb33-2b2ab40f8dea",
"amount": { "minor_units": 1000000, "currency": "MXN" },
"rate": { "numerator": 9, "denominator": 20, "quotation": "annual nominal", "percent": "45" },
"opens_on": "2026-08-24",
"expires_on": "2026-09-23",
"drawn": { "minor_units": 500000, "currency": "MXN" },
"headroom": { "minor_units": 500000, "currency": "MXN" },
"created_at": "2026-08-24T22:23:58.162514Z"
}
```
```json 404 No such grant theme={null}
{
"error": "facility: no such facility: not-a-uuid",
"code": "not_found"
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.