API Reference

API Reference

This reference covers all available endpoints, data structures, and query capabilities. Each example is tabbed for cURL, Python, JavaScript, and TypeScript.

Base URL & Headers

export BASE_URL="https://api.graphadv.com"
export GRAPHADV_API_KEY="YOUR_API_KEY"

Headers for every request:

• x-api-key: $GRAPHADV_API_KEY
• Content-Type: application/json

Method: POST to /firms, /funds, /filings, /principals, or /persons

Request body (all optional):

{
  "select": ["field_a", "field_b"],
  "filters": { "field_a": "eq.value" },
  "order": "field_a.desc",
  "limit": 25
}

• select — array of allowed fields (omit to return all).
• filters — key/value filters; values accept PostgREST operators (e.g., "aum_total_usd": "gte.1000000000" or "state": ["NY","CA"]).
• order — field.asc|desc[.nullsfirst|nullslast] (string or array for multiple clauses).
• limit — defaults to 25, max 50.

Response shape:

{ "data": [/* rows */], "total_count": 12345 }

API Credits

Each returned row consumes 1 credit; validated person rows consume 5 credits. Use select + limit to keep calls efficient.

Firms (POST /firms)

Fetch investment firms, hedge funds, and asset managers. Returns firm-level data including AUM, strategy classifications, investment approaches, and employee counts.

Key fields: legal_name, sec_number, region, strategy_class_primary, aum_total_usd, employee_count_total

See the Firms Schema for all available fields and detailed descriptions.

cURL

curl -X POST "$BASE_URL/firms" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["legal_name","sec_number","region","aum_total_usd","strategy_class_primary"],
    "order": "aum_total_usd.desc",
    "limit": 10
  }'

Python

import os
import requests

headers = {
    "x-api-key": os.getenv("GRAPHADV_API_KEY"),
    "Content-Type": "application/json",
}

response = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/firms",
    headers=headers,
    json={
        "select": ["legal_name", "sec_number", "region", "aum_total_usd", "strategy_class_primary"],
        "order": "aum_total_usd.desc",
        "limit": 10,
    },
)
firms = response.json()["data"]

JavaScript

const BASE_URL = process.env.BASE_URL ?? 'https://api.graphadv.com';
const response = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.GRAPHADV_API_KEY ?? '',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    select: ['legal_name', 'sec_number', 'region', 'aum_total_usd', 'strategy_class_primary'],
    order: 'aum_total_usd.desc',
    limit: 10
  })
});
const { data: firms } = await response.json();

TypeScript

const BASE_URL = process.env.BASE_URL ?? 'https://api.graphadv.com';
const response = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.GRAPHADV_API_KEY ?? '',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    select: ['legal_name', 'sec_number', 'region', 'aum_total_usd', 'strategy_class_primary'],
    order: 'aum_total_usd.desc',
    limit: 10
  })
});
const { data: firms } = (await response.json()) as { data: unknown[] };

Funds (POST /funds)

Fetch individual investment funds and vehicles. Returns fund-specific data including gross asset values, fund types, domicile information, and ownership structures.

Key fields: fund_business_key, fund_name, fund_type_label, gross_asset_value_usd, domicile_country, minimum_investment_usd

See the Funds Schema for all available fields and detailed descriptions.

cURL

curl -X POST "$BASE_URL/funds" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["fund_business_key","fund_name","fund_type_label","gross_asset_value_usd","domicile_country"],
    "order": "gross_asset_value_usd.desc",
    "limit": 10
  }'

Python

funds = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/funds",
    headers=headers,
    json={
        "select": ["fund_business_key", "fund_name", "fund_type_label", "gross_asset_value_usd", "domicile_country"],
        "order": "gross_asset_value_usd.desc",
        "limit": 10,
    },
).json()["data"]

JavaScript

const fundsResponse = await fetch(`${BASE_URL}/funds`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['fund_business_key', 'fund_name', 'fund_type_label', 'gross_asset_value_usd', 'domicile_country'],
    order: 'gross_asset_value_usd.desc',
    limit: 10
  })
});
const { data: funds } = await fundsResponse.json();

TypeScript

const fundsResponse = await fetch(`${BASE_URL}/funds`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['fund_business_key', 'fund_name', 'fund_type_label', 'gross_asset_value_usd', 'domicile_country'],
    order: 'gross_asset_value_usd.desc',
    limit: 10
  })
});
const { data: funds } = (await fundsResponse.json()) as { data: unknown[] };

Filings (POST /filings)

Fetch Form ADV Part 2 brochure filings with document metadata, firm associations, and extracted insights.

Key fields: filing_id, filing_type, filing_date, sequence_number, firm_id, document_id, public_url, extracts, insights

See the Filings Schema for all available fields and detailed descriptions.

cURL

curl -X POST "$BASE_URL/filings" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["document_id","filing_id","filing_type","filing_date","sequence_number","firm_id","public_url"],
    "order": "filing_date.desc",
    "limit": 10
  }'

Python

filings = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/filings",
    headers=headers,
    json={
        "select": ["document_id", "filing_id", "filing_type", "filing_date", "sequence_number", "firm_id", "public_url"],
        "order": "filing_date.desc",
        "limit": 10,
    },
).json()["data"]

JavaScript

const filingsResponse = await fetch(`${BASE_URL}/filings`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['document_id', 'filing_id', 'filing_type', 'filing_date', 'sequence_number', 'firm_id', 'public_url'],
    order: 'filing_date.desc',
    limit: 10
  })
});
const { data: filings } = await filingsResponse.json();

TypeScript

const filingsResponse = await fetch(`${BASE_URL}/filings`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['document_id', 'filing_id', 'filing_type', 'filing_date', 'sequence_number', 'firm_id', 'public_url'],
    order: 'filing_date.desc',
    limit: 10
  })
});
const { data: filings } = (await filingsResponse.json()) as { data: unknown[] };

Principals (POST /principals)

Fetch key executives, fund managers, and decision-makers. Returns individual-level data including names, titles, and firm associations.

Key fields: full_name, title, role_category, relationship_role, email_is_validated, firm_business_key

See the Principals Schema for all available fields and detailed descriptions.

cURL

curl -X POST "$BASE_URL/principals" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["full_name","title","role_category","relationship_role","email_is_validated","firm_business_key","firm_sec_number"],
    "order": "full_name.asc",
    "limit": 10
  }'

Python

principals = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/principals",
    headers=headers,
    json={
        "select": ["full_name", "title", "role_category", "relationship_role", "email_is_validated", "firm_business_key", "firm_sec_number"],
        "order": "full_name.asc",
        "limit": 10,
    },
).json()["data"]

JavaScript

const principalsResponse = await fetch(`${BASE_URL}/principals`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['full_name', 'title', 'role_category', 'relationship_role', 'email_is_validated', 'firm_business_key', 'firm_sec_number'],
    order: 'full_name.asc',
    limit: 10
  })
});
const { data: principals } = await principalsResponse.json();

TypeScript

const principalsResponse = await fetch(`${BASE_URL}/principals`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['full_name', 'title', 'role_category', 'relationship_role', 'email_is_validated', 'firm_business_key', 'firm_sec_number'],
    order: 'full_name.asc',
    limit: 10
  })
});
const { data: principals } = (await principalsResponse.json()) as { data: unknown[] };

Persons (POST /persons)

Fetch normalized person entities with identity, contact, and affiliation signals that power cross-dataset person resolution.

Key fields (examples): person_business_key, full_name, email_is_validated, email_confidence, linkedin_url, address_state, has_disclosures

See the Persons Schema for all available fields and detailed descriptions.

cURL

curl -X POST "$BASE_URL/persons" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["person_business_key","full_name","email_is_validated","email_confidence","linkedin_url","address_state"],
    "order": "email_confidence.desc",
    "limit": 10
  }'

Python

persons = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/persons",
    headers=headers,
    json={
        "select": ["person_business_key", "full_name", "email_is_validated", "email_confidence", "linkedin_url", "address_state"],
        "order": "email_confidence.desc",
        "limit": 10,
    },
).json()["data"]

JavaScript

const personsResponse = await fetch(`${BASE_URL}/persons`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['person_business_key', 'full_name', 'email_is_validated', 'email_confidence', 'linkedin_url', 'address_state'],
    order: 'email_confidence.desc',
    limit: 10
  })
});
const { data: persons } = await personsResponse.json();

TypeScript

const personsResponse = await fetch(`${BASE_URL}/persons`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['person_business_key', 'full_name', 'email_is_validated', 'email_confidence', 'linkedin_url', 'address_state'],
    order: 'email_confidence.desc',
    limit: 10
  })
});
const { data: persons } = (await personsResponse.json()) as { data: unknown[] };

Filtering & Sorting

Combine multiple filters and sort results in a single query. This example finds hedge funds in the Northeast region with over $10B in assets, sorted by AUM (largest first).

Key Query Operators:

• cs.{VALUE} - Contains (for array fields like strategy_class_primary)
• eq.VALUE - Equals (for text fields like region)
• gte.VALUE - Greater than or equal (for numeric fields like aum_total_usd)
• order - field.desc or field.asc (add .nullsfirst|nullslast if needed)

cURL

curl -X POST "$BASE_URL/firms" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["legal_name","region","aum_total_usd","strategy_class_primary"],
    "filters": {
      "strategy_class_primary": "cs.{HEDGE_FUND}",
      "region": "eq.Northeast",
      "aum_total_usd": "gte.10000000000"
    },
    "order": "aum_total_usd.desc",
    "limit": 25
  }'

Python

filtered = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/firms",
    headers=headers,
    json={
        "select": ["legal_name", "region", "aum_total_usd", "strategy_class_primary"],
        "filters": {
            "strategy_class_primary": "cs.{HEDGE_FUND}",
            "region": "eq.Northeast",
            "aum_total_usd": "gte.10000000000",
        },
        "order": "aum_total_usd.desc",
    },
).json()["data"]

JavaScript

const filteredResponse = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'region', 'aum_total_usd', 'strategy_class_primary'],
    filters: {
      strategy_class_primary: 'cs.{HEDGE_FUND}',
      region: 'eq.Northeast',
      aum_total_usd: 'gte.10000000000'
    },
    order: 'aum_total_usd.desc'
  })
});
const { data: filtered } = await filteredResponse.json();

TypeScript

const filteredResponse = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'region', 'aum_total_usd', 'strategy_class_primary'],
    filters: {
      strategy_class_primary: 'cs.{HEDGE_FUND}',
      region: 'eq.Northeast',
      aum_total_usd: 'gte.10000000000'
    },
    order: 'aum_total_usd.desc'
  })
});
const { data: filtered } = (await filteredResponse.json()) as { data: unknown[] };

Counting & Pagination

The proxy returns total_count in the JSON response when Supabase provides a count. Use limit (max 50) to size pages. Offset-based pagination is not exposed; page by ordering on a stable field and filtering by the last value you saw.

cURL

curl -X POST "$BASE_URL/firms" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "select": ["legal_name","sec_number","aum_total_usd"],
    "filters": { "region": "eq.Northeast" },
    "order": "aum_total_usd.desc",
    "limit": 25
  }'

Python

page = requests.post(
    f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/firms",
    headers=headers,
    json={
        "select": ["legal_name", "sec_number", "aum_total_usd"],
        "filters": {"region": "eq.Northeast"},
        "order": "aum_total_usd.desc",
        "limit": 25,
    },
).json()
firms = page["data"]
total = page.get("total_count")

JavaScript

const resp = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'sec_number', 'aum_total_usd'],
    filters: { region: 'eq.Northeast' },
    order: 'aum_total_usd.desc',
    limit: 25
  })
});
const { data: firms, total_count } = await resp.json();

TypeScript

const resp = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'sec_number', 'aum_total_usd'],
    filters: { region: 'eq.Northeast' },
    order: 'aum_total_usd.desc',
    limit: 25
  })
});
const { data: firms, total_count } = (await resp.json()) as { data: unknown[]; total_count: number | null };

Joins & Relationships

Nested relationship selects (e.g., funds(*) inside firms) are not exposed through the proxy today. Fetch related data with multiple calls—first grab the parent, then query the child table with a filter.

Example: fetch principals for a given firm:

1. POST /firms with filters: { sec_number: "eq.801-123456" } to get the firm id.
2. POST /principals with filters: { firm_id: "<id from step 1>" } to pull related principals.

Error Handling & Rate Limits

Always check response status codes and handle errors appropriately. The API returns standard HTTP status codes and may include rate limit headers.

Common HTTP Status Codes:

• 200 OK - Request succeeded
• 400 Bad Request - Invalid query syntax or parameters
• 401 Unauthorized - Missing or invalid API key
• 404 Not Found - Endpoint or resource doesn’t exist
• 429 Too Many Requests - Rate limit exceeded

Rate Limit Headers (if implemented):

• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Unix timestamp when the limit resets

cURL

response=$(curl -i -X POST "$BASE_URL/firms" \
  -H "x-api-key: $GRAPHADV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":1}')

echo "$response" | head -n 1

Python

resp = requests.post(f"{os.getenv('BASE_URL', 'https://api.graphadv.com')}/firms", headers=headers, json={"limit": 1})
resp.raise_for_status()
remaining = resp.headers.get("X-RateLimit-Remaining")
reset = resp.headers.get("X-RateLimit-Reset")

JavaScript

const resp = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({ limit: 1 })
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.info('Remaining', resp.headers.get('X-RateLimit-Remaining'));
console.info('Resets at', resp.headers.get('X-RateLimit-Reset'));

TypeScript

const resp = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': process.env.GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({ limit: 1 })
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.info('Remaining', resp.headers.get('X-RateLimit-Remaining'));
console.info('Resets at', resp.headers.get('X-RateLimit-Reset'));

Query Operators Reference

GraphADV uses PostgREST query syntax. Here are the most commonly used operators:

Comparison Operators:

• eq.VALUE - Equals
• neq.VALUE - Not equals
• gt.VALUE - Greater than
• gte.VALUE - Greater than or equal
• lt.VALUE - Less than
• lte.VALUE - Less than or equal

Pattern Matching:

• like.PATTERN - Case-sensitive pattern match (use % as wildcard)
• ilike.PATTERN - Case-insensitive pattern match (use * as wildcard in PostgREST)

Array Operators:

• cs.{VALUE1,VALUE2} - Contains (array contains these values)
• cd.{VALUE1,VALUE2} - Contained by (array is subset of these values)
• ov.{VALUE1,VALUE2} - Overlaps (array has any of these values)

Null Checks:

• is.null - Field is null
• not.is.null - Field is not null

Logical Operators:

• and - Combine filters with AND (default behavior when chaining parameters)
• or - Combine filters with OR (e.g., or=(field1.eq.value1,field2.eq.value2))

For the complete reference, see the PostgREST documentation.

Related Reading

• Pagination
• Examples
• Firms Schema
• Funds Schema
• Principals Schema
• Persons Schema
• Principals Schema