top_n
Retrieves the top or bottom N rows by a chosen measure from APRA datasets, enabling ranking of entities by capital, members, or other metrics.
Instructions
Return the N rows with the largest (or smallest) value of a measure.
The single most common agent workflow: "show me the top 10 X by Y". top_n does the rank server-side and returns only the requested rows.
Examples: # Biggest 10 banks by total capital, latest quarter top_n("ADI_KEY_STATS", "total_capital", n=10, filters={"period": "2025-12-31"})
# Most members per super fund (latest)
top_n("SUPER_FUND_LEVEL", "total_member_accounts", n=10,
filters={"period": "2025-12-31"})
# 5 lowest CET1 ratios in the latest quarter
top_n("ADI_KEY_STATS", "cet1_ratio", n=5, direction="bottom",
filters={"period": "2025-12-31"})Returns:
DataResponse with at most n records, sorted by measure in the
requested direction. Other fields match get_data.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | Curated dataset ID. | |
| measure | Yes | Plain-English measure key to rank by. Use describe_dataset() to see available measures. | |
| n | No | How many top (or bottom) rows to return. | |
| filters | No | Optional dimension filters, same shape as get_data. Typically you'll pin a single period to make rank meaningful (e.g. {'period': '2025-12-31'} for the latest quarter). | |
| direction | No | 'top' returns the N rows with the LARGEST measure values (biggest bank, highest capital, largest fund). 'bottom' returns the SMALLEST. | top |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes | ||
| dataset_name | Yes | ||
| query | No | ||
| period | No | ||
| unit | No | ||
| row_count | No | ||
| records | No | ||
| csv | No | ||
| source | No | Australian Prudential Regulation Authority | |
| attribution | No | Source: Australian Prudential Regulation Authority. Licensed under Creative Commons Attribution 3.0 Australia (https://creativecommons.org/licenses/by/3.0/au/). | |
| retrieved_at | Yes | ||
| apra_url | Yes | ||
| download_url | No | ||
| framework | No | ||
| stale | No | ||
| stale_reason | No | ||
| server_version | No |