claude-scientific-skills/scientific-skills/hedgefundmonitor/references/endpoints-metadata.md

Metadata Endpoints

1. List Mnemonics — /metadata/mnemonics

URL: GET https://data.financialresearch.gov/hf/v1/metadata/mnemonics

Returns all series identifiers available through the API.

Parameters

Parameter	Type	Required	Description
dataset	string	No	Filter by dataset key: fpf, tff, scoos, ficc
output	string	No	by_dataset — returns a hash grouped by dataset

Examples

import requests
BASE = "https://data.financialresearch.gov/hf/v1"

# All mnemonics (flat list)
resp = requests.get(f"{BASE}/metadata/mnemonics")
mnemonics = resp.json()
# Returns: ["FPF-ALLQHF_CDSDOWN250BPS_P5", "FPF-ALLQHF_CDSDOWN250BPS_P50", ...]

# Mnemonics for a single dataset with names
resp = requests.get(f"{BASE}/metadata/mnemonics", params={"dataset": "fpf"})
# Returns: [{"mnemonic": "FPF-ALLQHF_CDSDOWN250BPS_P5", "series_name": "Stress test: CDS spreads decrease 250 basis points net impact on NAV (5th percentile fund)"}, ...]

# All mnemonics grouped by dataset
resp = requests.get(f"{BASE}/metadata/mnemonics", params={"output": "by_dataset"})
grouped = resp.json()
# Returns: {"ficc": [{mnemonic, series_name}, ...], "fpf": [...], ...}

---

2. Single Series Query — /metadata/query

URL: GET https://data.financialresearch.gov/hf/v1/metadata/query

Returns full metadata for a single mnemonic.

Parameters

Parameter	Type	Required	Description
mnemonic	string	Yes	The series mnemonic
fields	string	No	Comma-separated list of fields to retrieve. Use / to access subfields (e.g., release/long_name)

Metadata Fields

The metadata object includes these top-level fields (with subfields):

Field	Subfields
mnemonic	—
description	name, description, notes, vintage_approach, vintage, subsetting, subtype
schedule	observation_period, observation_frequency, seasonal_adjustment, start_date, last_update
release	long_name, short_name, and other release-level metadata

Examples

# Full metadata
resp = requests.get(f"{BASE}/metadata/query", params={
    "mnemonic": "fpf-allqhf_cdsup250bps_p5"
})
meta = resp.json()
print(meta["description"]["name"])
print(meta["schedule"]["start_date"])
print(meta["schedule"]["observation_frequency"])

# Specific subfield only
resp = requests.get(f"{BASE}/metadata/query", params={
    "mnemonic": "fpf-allqhf_cdsup250bps_p5",
    "fields": "release/long_name"
})
# Returns: {"release": {"long_name": "Hedge Fund Aggregated Statistics from SEC Form PF Filings"}}

# Multiple fields
resp = requests.get(f"{BASE}/metadata/query", params={
    "mnemonic": "fpf-allqhf_cdsup250bps_p5",
    "fields": "description/name,schedule/start_date,schedule/observation_frequency"
})

---

3. Series Search — /metadata/search

URL: GET https://data.financialresearch.gov/hf/v1/metadata/search

Full-text search across all metadata fields. Supports wildcards.

Parameters

Parameter	Type	Required	Description
query	string	Yes	Search string. Supports * (multi-char wildcard) and ? (single-char wildcard)

Response Fields

Each result object contains:

Field	Description
mnemonic	Series identifier (or "none" for dataset-level metadata)
dataset	Dataset key (fpf, tff, scoos, ficc)
field	Which metadata field matched (e.g., description/name)
value	The matched field value
type	Data type (str, etc.)

Examples

# Find series containing "leverage" anywhere
resp = requests.get(f"{BASE}/metadata/search", params={"query": "*leverage*"})
results = resp.json()
for r in results:
    print(r["mnemonic"], r["field"], r["value"])

# Find series starting with "Fund"
resp = requests.get(f"{BASE}/metadata/search", params={"query": "Fund*"})

# Find by exact dataset name
resp = requests.get(f"{BASE}/metadata/search", params={"query": "FICC*"})

# Search for stress test series
resp = requests.get(f"{BASE}/metadata/search", params={"query": "*stress*"})

# Get unique mnemonics from search results
results = resp.json()
mnemonics = list({r["mnemonic"] for r in results if r["mnemonic"] != "none"})