Plinth US Grants Data Meta API

Dataset scope, source freshness, and which Candid parameters this API honors. No key required.

GitHub OpenAPI

Operations 1

1 of 1 operations are conformant: apis.io called them with no credentials and the responses matched this contract. Checked 2026-11-12. how this works · status file

GET /api/v1/meta Dataset scope, freshness and the Candid compatibility matrix conformant #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/plinth-us-grants-data:plinth-us-grants-data-meta-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

plinth-us-grants-data-meta-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Plinth Grants Meta API
  summary: US foundation and nonprofit funding data from public IRS Form 990 and 990-PF filings.
  description: 'A read API over the US grantmaking universe, read from public IRS Form 990, 990-EZ and 990-PF e-file filings.


    The funder-grantee graph traverses in BOTH directions: filter by `funder_id` for everything a foundation funded, or by `recip_id` for every funder behind a nonprofit.


    Start with `/api/v1/search` to turn an organization name into an EIN and a canonical page URL — it needs no key. The grant endpoints need a free key (50 calls a day); the organization endpoints (/compliance, /essentials, /premier) need a paid one.


    **No CORS headers, deliberately.** This is a server-side API: a key in browser JavaScript is a key you have published, and every allowance here is per-key. Call it from your backend, or from an agent. There is no browser-callable subset planned.


    Figures are read directly from named IRS filings. The IRS releases e-file data on a 12-24 month lag, so every figure is dated to its fiscal year rather than to today. Funding relationships are reported as association, never as causation. Organizations that do not e-file may be absent.'
  version: 1.0.0
  contact:
    name: Plinth
    url: https://data.useplinth.com/developers
  license:
    name: 'Source data: IRS public domain'
    url: https://www.irs.gov/charities-non-profits/tax-exempt-organization-search-bulk-data-downloads
  termsOfService: https://data.useplinth.com/terms
servers:
- url: https://data.useplinth.com
  description: Plinth US philanthropy data
security:
- ApiKeyAuth: []
tags:
- name: Meta
  description: Dataset scope, source freshness, and which Candid parameters this API honors. No key required.
paths:
  /api/v1/meta:
    get:
      summary: Dataset scope, freshness and the Candid compatibility matrix
      description: '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.'
      operationId: getMeta
      parameters:
      - name: jurisdiction
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Jurisdiction
          examples:
          - us
        description: 'Filing jurisdiction of the GRANT: us (default) | ca. Never mixed — amounts stay in the currency the filing was made in and are never converted, so every total is a single-jurisdiction total. `x_plinth.dataset` names the source, licence and currency behind the answer. Distinct from `country`, which is where the RECIPIENT sits.'
      responses:
        '200':
          description: What this deployment holds, and how to get a key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Meta
      security: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResponseWarning:
      properties:
        parameter:
          type: string
          title: Parameter
        severity:
          type: string
          title: Severity
          description: '`caveat` informs; anything else means a filter did NOT apply.'
        reason:
          type: string
          title: Reason
      type: object
      required:
      - parameter
      - severity
      - reason
      title: ResponseWarning
      description: A parameter we recognized but could not honor, named rather than silently dropped.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MetaScope:
      properties:
        grants:
          anyOf:
          - type: integer
          - type: 'null'
          title: Grants
        total_amount:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Amount
        funders:
          anyOf:
          - type: integer
          - type: 'null'
          title: Funders
        first_fiscal_year:
          anyOf:
          - type: integer
          - type: 'null'
          title: First Fiscal Year
        last_fiscal_year:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Fiscal Year
          description: 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:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Complete Fiscal Year
          description: Newest fiscal year that has finished arriving — the span to quote. Null on a slice too thin to measure, never guessed.
        partial_fiscal_years:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Partial Fiscal Years
          description: '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.'
      type: object
      title: MetaScope
      description: '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).'
    ExcludedClass:
      properties:
        grants:
          anyOf:
          - type: integer
          - type: 'null'
          title: Grants
          description: Rows dropped. Null when the cost could not be measured — see `unavailable`.
        dollars:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dollars
          description: Dollars dropped. Null when the cost could not be measured.
        definition:
          anyOf:
          - type: string
          - type: 'null'
          title: Definition
          description: What this class means, single-sourced from config/candid-compat.json.
        unavailable:
          anyOf:
          - type: string
          - type: 'null'
          title: Unavailable
          description: Present only when the accounting failed. The totals in the response are unaffected — a failed measurement never fails a correct answer.
      type: object
      title: ExcludedClass
      description: What one `?exclude=` class cost, measured against the caller's own filter.
    Unidentified:
      properties:
        grants:
          anyOf:
          - type: integer
          - type: 'null'
          title: Grants
        dollars:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dollars
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
        unavailable:
          anyOf:
          - type: string
          - type: 'null'
          title: Unavailable
          description: Present only when the size could not be computed. The ranking above is unaffected.
      type: object
      title: Unidentified
      description: Grants held OUT of a recipient ranking because their recipient is not an organization.
    DatasetStamp:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        refresh:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh
        polled:
          anyOf:
          - type: string
          - type: 'null'
          title: Polled
          description: How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one.
        reporting_lag:
          anyOf:
          - type: string
          - type: 'null'
          title: Reporting Lag
          description: Why a figure is dated to a fiscal year rather than to today.
        basis:
          anyOf:
          - type: string
          - type: 'null'
          title: Basis
          description: 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:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
          description: Opaque build stamp of the data slice. Changes only when the data does.
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Generated At
          description: ISO 8601 timestamp the slice was built.
        license:
          anyOf:
          - type: string
          - type: 'null'
          title: License
          description: Licence the source data is published under, where it carries one. Absent for public-domain sources.
        attribution:
          anyOf:
          - type: string
          - type: 'null'
          title: Attribution
          description: Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction.
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
          description: Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures.
      type: object
      title: DatasetStamp
      description: Provenance of the slice that answered. `version` is the sync signal — poll it, re-pull when it moves.
    XPlinth:
      properties:
        warnings:
          anyOf:
          - items:
              $ref: '#/components/schemas/ResponseWarning'
            type: array
          - type: 'null'
          title: Warnings
        unsupported:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Unsupported
          description: Parameters that did not apply. Non-empty means the answer is not the question asked.
        dataset:
          anyOf:
          - $ref: '#/components/schemas/DatasetStamp'
          - type: 'null'
        datasets:
          anyOf:
          - items:
              $ref: '#/components/schemas/DatasetStamp'
            type: array
          - type: 'null'
          title: Datasets
          description: '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.'
        excluded:
          anyOf:
          - additionalProperties:
              anyOf:
              - $ref: '#/components/schemas/ExcludedClass'
              - type: boolean
            type: object
          - type: 'null'
          title: Excluded
          description: 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:
          anyOf:
          - $ref: '#/components/schemas/Unidentified'
          - type: 'null'
          description: 'On /grants/recipients: the grants held out of the ranking because their recipient is a person, a class of people, or nobody the filer named. Add these back to reconcile with /grants/summary.'
      type: object
      title: XPlinth
      description: Non-Candid metadata. Safe to ignore for compatibility; `unsupported` is the one to assert on.
    MetaResponse:
      properties:
        code:
          type: integer
          title: Code
          default: 200
        message:
          type: string
          title: Message
        x_plinth:
          anyOf:
          - $ref: '#/components/schemas/XPlinth'
          - type: 'null'
        dataset:
          $ref: '#/components/schemas/DatasetStamp'
        scope:
          $ref: '#/components/schemas/MetaScope'
        trial:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Trial
          description: How to get a key with no account, and what it may read.
        compliance_sources:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Compliance Sources
        candid_compatibility:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Candid Compatibility
      type: object
      required:
      - message
      - dataset
      - scope
      title: MetaResponse
      description: What this deployment holds and how to reach it. Needs no key — start here.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Free key includes 50 calls a day across /grants/*; the organization endpoints and SQL need a paid plan. Get one at https://data.useplinth.com/pricing.
externalDocs:
  description: Developer documentation
  url: https://data.useplinth.com/developers