---
title: "Dataset scope, freshness and the Candid compatibility matrix"
method: GET
path: "/api/v1/meta"
tags: ["Meta"]
---

# Dataset scope, freshness and the Candid compatibility matrix

`GET /api/v1/meta`

## Request

- Base URL: `https://data.useplinth.com`
- URL: `https://data.useplinth.com/api/v1/meta`
- Auth: none required

What is in the corpus, how current it is, and which Candid parameters this API honors. This is the answer to Candid's `last_updated` filter: there is no per-row change stamp because the dataset is rebuilt as a whole from monthly IRS releases, so a client keeping its own copy in sync watches `dataset.version` and the fiscal year span here and re-pulls when either moves. Keyless and unmetered.

**`scope` carries TWO fiscal-year ends and they are not the same number.** `last_fiscal_year` is the newest year any row falls in — sync against this. `last_complete_fiscal_year` is the newest year that has finished arriving, and it is the one to quote in prose: the IRS releases e-file data 12-24 months after the activity, so the corpus always holds a few hundred early filings for a year that has barely begun. `partial_fiscal_years` names every year still filling. Reporting `last_fiscal_year` as the coverage span overstates it by a year or two.

## Query parameters

- `jurisdiction` string, nullable

## Response `200`

What this deployment holds, and how to get a key.

- MetaResponse: What this deployment holds and how to reach it. Needs no key — start here.
  - `code` integer
  - `message` string, required
  - `x_plinth` XPlinth: Non-Candid metadata. Safe to ignore for compatibility; `unsupported` is the one to assert on.
    - `warnings` ResponseWarning[], nullable
      - `parameter` string, required
      - `severity` string, required: `caveat` informs; anything else means a filter did NOT apply.
      - `reason` string, required
    - `unsupported` string[], nullable: Parameters that did not apply. Non-empty means the answer is not the question asked.
    - `dataset` DatasetStamp: Provenance of the slice that answered. `version` is the sync signal — poll it, re-pull when it moves.
      - `source` string, nullable
      - `refresh` string, nullable
      - `polled` string, nullable: How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one.
      - `reporting_lag` string, nullable: Why a figure is dated to a fiscal year rather than to today.
      - `basis` string, nullable: Grants PAID versus grants approved — the reconciliation that catches people comparing a total here to a funder's own published giving figure. Read it before filing a discrepancy.
      - `version` string, nullable: Opaque build stamp of the data slice. Changes only when the data does.
      - `generated_at` string, nullable: ISO 8601 timestamp the slice was built.
      - `license` string, nullable: Licence the source data is published under, where it carries one. Absent for public-domain sources.
      - `attribution` string, nullable: Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction.
      - `currency` string, nullable: Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures.
    - `datasets` DatasetStamp[], nullable: Every corpus this response could have drawn on, each with its own licence terms. /sql only: you write the query, so which corpus answered is not knowable per response — honour every licence listed.
      - `source` string, nullable
      - `refresh` string, nullable
      - `polled` string, nullable: How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one.
      - `reporting_lag` string, nullable: Why a figure is dated to a fiscal year rather than to today.
      - `basis` string, nullable: Grants PAID versus grants approved — the reconciliation that catches people comparing a total here to a funder's own published giving figure. Read it before filing a discrepancy.
      - `version` string, nullable: Opaque build stamp of the data slice. Changes only when the data does.
      - `generated_at` string, nullable: ISO 8601 timestamp the slice was built.
      - `license` string, nullable: Licence the source data is published under, where it carries one. Absent for public-domain sources.
      - `attribution` string, nullable: Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction.
      - `currency` string, nullable: Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures.
    - `excluded` object, nullable: Per-class cost of `?exclude=`, keyed by class name, plus `overlapping` — true when classes were counted independently and therefore sum to more than the whole. /grants/summary only.
    - `unidentified` Unidentified: Grants held OUT of a recipient ranking because their recipient is not an organization.
      - `grants` integer, nullable
      - `dollars` integer, nullable
      - `note` string, nullable
      - `unavailable` string, nullable: Present only when the size could not be computed. The ranking above is unaffected.
  - `dataset` DatasetStamp, required: Provenance of the slice that answered. `version` is the sync signal — poll it, re-pull when it moves.
    - `source` string, nullable
    - `refresh` string, nullable
    - `polled` string, nullable: How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one.
    - `reporting_lag` string, nullable: Why a figure is dated to a fiscal year rather than to today.
    - `basis` string, nullable: Grants PAID versus grants approved — the reconciliation that catches people comparing a total here to a funder's own published giving figure. Read it before filing a discrepancy.
    - `version` string, nullable: Opaque build stamp of the data slice. Changes only when the data does.
    - `generated_at` string, nullable: ISO 8601 timestamp the slice was built.
    - `license` string, nullable: Licence the source data is published under, where it carries one. Absent for public-domain sources.
    - `attribution` string, nullable: Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction.
    - `currency` string, nullable: Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures.
  - `scope` MetaScope, required: Headline counts for the slice currently being served — the live figure any copy should track. ⚠️ THE TWO YEAR ENDS ARE DIFFERENT NUMBERS AND BOTH ARE PUBLISHED. `last_fiscal_year` is max(tax_year) — sync a mirrored copy against it. `last_complete_fiscal_year` is the newest year that has stopped filling, and it is the one prose should quote: the IRS lag means the corpus always carries a few hundred early filings for a barely-started year, so max(tax_year) reads a year or two ahead of the coverage anyone would recognise. Publishing only the first is what put /meta at FY2026 while every page on the site said FY2025 (2026-08 audit).
    - `grants` integer, nullable
    - `total_amount` integer, nullable
    - `funders` integer, nullable
    - `first_fiscal_year` integer, nullable
    - `last_fiscal_year` integer, nullable: Newest fiscal year any row falls in — max(tax_year), including years still arriving. Sync against this; do not quote it as the coverage span.
    - `last_complete_fiscal_year` integer, nullable: Newest fiscal year that has finished arriving — the span to quote. Null on a slice too thin to measure, never guessed.
    - `partial_fiscal_years` integer[], nullable: Fiscal years still filling. Measured the same way /data-quality measures it: a trailing year holding less than 90% of the year before it has not finished arriving. The newest year is always here.
  - `trial` object, nullable: How to get a key with no account, and what it may read.
  - `compliance_sources` object, nullable
  - `candid_compatibility` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/useplinth/apis/plinth-grants-api.md) · [All operations](https://skmtc.dev/useplinth/apis/plinth-grants-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useplinth/apis/plinth-grants-api/revisions/15273cd72ecf?raw)