Metrics¶

Metrics endpoints return time-series obligation and award counts for a specific entity, NAICS code, or PSC code. They share the same URL pattern and query parameters, so this page describes behavior once, then lists the available endpoints.

How metrics work¶

Each metrics endpoint is:

GET /api/{resource}/{id}/metrics/<months>/<period_grouping>/

• Path parameters (required):
• {id} — The resource identifier (entity UEI, NAICS code, or PSC code).
• months — Lookback window in months (positive integer). Example: 24 for the last 24 months.

• period_grouping — How to bucket time: year, quarter, or month.

• Query parameters (optional):

• group_by — Comma-separated list of dimensions to break out: agency, department. When used, each result row includes the grouped dimension(s). Rolling averages are not supported when grouping; if both are used, rolling is skipped and a warning is returned.
• fiscal_year — If true or 1, buckets use federal fiscal year (Oct–Sep). Default is calendar year.
• rolling — If true or 1, adds a rolling average to each result (when not using group_by).

Response shape (same for all three):

• count — Number of result rows.
• description — Human-readable description of the time range and grouping.
• warning — Present only when e.g. rolling was requested with group_by (rolling skipped).
• The resource object — recipient (entity), naics_code, or psc_code (the one you queried).
• results — Array of objects. Each has:
• year (and optionally month, quarter depending on period_grouping),
• awards, subawards (obligation/count values),
• rolling_avg (if rolling=true and no group_by),
• department, agency (if group_by includes them).

Invalid period_grouping, non-positive months, or invalid group_by values return HTTP 400 with an error message.

Available endpoints¶

All three support the same optional query parameters: group_by, fiscal_year, rolling.

Example¶

Entity obligations for the last 12 months, by month, with rolling average:

GET /api/entities/ABC123DEF456/metrics/12/month/?rolling=true

NAICS code 541512 for the last 24 months by quarter, grouped by department:

GET /api/naics/541512/metrics/24/quarter/?group_by=department

SDK¶

The official SDKs don’t yet expose first-class methods for metrics. Use the HTTP helper with the paths above:

import os

from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
data = client._get(
    "/api/entities/ABC123DEF456/metrics/12/month/",
    params={"rolling": "true"},
)
print("count:", data.get("count"), "results:", len(data.get("results", [])))

import { TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
const http = (client as any).http;

const data = await http.get("/api/entities/ABC123DEF456/metrics/12/month/", {
  rolling: "true",
});
console.log("count:", data.count, "results:", data.results?.length ?? 0);