/api/v1/patents/aggregatePatent Aggregates
Fast pre-computed aggregate patent counts (patent_agg_* tables), grouped by year, CPC code and/or company - group_by accepts a comma-separated subset of 'year','cpc','company'. IMPORTANT: country and legal_status are NOT supported here (HTTP 400) - use patents.search for those. The year range defaults to the current year and the two preceding calendar years; pass publication_date_from/to to widen it. Company filters accept an exact raw assignee string, 'organizations/<key>', 'ror:<id>' or 'lei:<id>'; unresolved company values and unknown CPC prefixes return HTTP 400 naming the value (never silently dropped). meta.total_buckets is the number of buckets returned, not the number of groups. Requires a Pro workspace (returns HTTP 402 otherwise). Use patents.search for listings and patents.yoy-growth for growth deltas.
When to use it
- patents per year for a company or CPC class
- CPC / company distribution within a portfolio (one call, multiple group_by values)
- quick portfolio sizing without fetching listings
Getting started
Base URL
https://app.caelrith.com/api/v1/toolsAuthentication
Include your API key in the x-api-key header.
Parameters
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| group_by | string | No | Comma-separated subset of 'year', 'cpc', 'company' (e.g. 'year,company'; default 'year'). Each dimension produces one bucket per value with a 'count'. |
| company_id | string | No | Organization to filter on. Accepts an exact raw assignee string (as it appears in a patent's assignees array), 'organizations/<key>', 'ror:<id>', 'lei:<id>', or a bare ROR/LEI id. Takes precedence over company_name. Unresolved values return HTTP 400 (never silently ignored). |
| company_name | string | No | Resolved organization name, used as a fallback when company_id is not provided. |
| cpc_code | string | No | CPC classification code or prefix (e.g. 'A61K'). |
| include_descendants | string | No | When true (default), a cpc_code prefix expands to every code starting with it; set false for exact-code matches only. Allowed values: true, false |
| publication_date_from | string | No | YYYY-MM-DD; restricts the counted window (defaults to the current year and the two preceding calendar years). |
| publication_date_to | string | No | YYYY-MM-DD; restricts the counted window. |
| limit | integer | No | Maximum number of buckets to return (1-500, default 100). Range: 1 to 500 |
| sort_by_count | string | No | Sort buckets by count (default desc). Allowed values: desc, asc |
Example request
curl -H "x-api-key: YOUR_API_KEY" \ "https://app.caelrith.com/api/v1/patents/aggregate"
Response envelope
Successful responses wrap the payload in a success flag.
{
"success": true,
"buckets": { /* payload */ },
"meta": { /* pagination, totals */ }
}Response shape
Payload: data — Patent Counts
Exact total: meta.total_buckets
Common row fields
| Field | Description |
|---|---|
| year | Year |
| cpc | CPC |
| company | Company |
| count | Count |
Empty results: No matching rows (HTTP 200)
Rows are pre-computed buckets: {year|count}, {cpc|count} or {company|count} depending on group_by - the row's 'count' is the number of patents. meta.total_buckets is the number of buckets RETURNED after limit (max 500) - a page size, not the true number of groups; the EXACT TOTAL line is that returned bucket count, NOT a patent count. Unresolved company values and unknown CPC prefixes are rejected with HTTP 400 naming the value (never silently dropped); meta.filters.company_id_resolved / company_cluster_size echo the resolved anchor (null / 0 when absent). country / legal_status are rejected with HTTP 400 - use patents.search for those.
Catalog version 0.0.0-generated · generated from the API source