Getting Started

Getting Started

This guide will walk you through making your first API request to GraphADV. Every code sample is presented in cURL, Python, JavaScript, and TypeScript so you can swap languages without scrolling.

Prerequisites

Before you begin, you’ll need:

• An API key (get one at graphadv.com)
• Basic knowledge of REST APIs and HTTP requests

Step 1: Get Your API Key

1. Visit graphadv.com
2. Click Get API Key
3. Sign in with your email address or Google account
4. Your API key will be generated and displayed immediately
5. Copy and securely store your API key

Keep Your API Key Secret

Your API key grants access to your account and data. Never share it publicly or commit it to version control. Store it securely as an environment variable.

Step 2: Set Your Environment

Set these values once and reuse them across every snippet:

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

All requests share the same headers:

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

Step 3: Understand the Proxy Request Body

The Fly.io proxy expects a POST with a compact JSON payload:

{
  "select": ["legal_name", "sec_number", "region", "aum_total_usd"],
  "filters": { "region": "eq.Northeast" },
  "order": "aum_total_usd.desc",
  "limit": 5
}

• select (array) — fields to return. Omit for all default fields.
• filters (object) — key/value filters. Values support PostgREST operators (e.g., "aum_total_usd": "gte.1000000000").
• order (string or array) — field.asc|desc[.nullsfirst|nullslast].
• limit (number) — defaults to 25, capped at 50.

Make Your First Request

The base URL for all API requests is https://api.graphadv.com.

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"],
    "filters": { "region": "eq.Northeast" },
    "order": "aum_total_usd.desc",
    "limit": 5
  }'

Python

import os
import requests

BASE_URL = os.getenv("BASE_URL", "https://api.graphadv.com")
API_KEY = os.getenv("GRAPHADV_API_KEY")

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "select": ["legal_name", "sec_number", "region", "aum_total_usd"],
    "filters": {"region": "Northeast"},
    "order": "aum_total_usd.desc",
    "limit": 5,
}

response = requests.post(f"{BASE_URL}/firms", headers=headers, json=payload)
firms = response.json()["data"]

JavaScript

const BASE_URL = process.env.BASE_URL ?? 'https://api.graphadv.com';
const GRAPHADV_API_KEY = process.env.GRAPHADV_API_KEY;

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

const { data: firms } = await response.json();

TypeScript

const BASE_URL = process.env.BASE_URL ?? 'https://api.graphadv.com';
const GRAPHADV_API_KEY = process.env.GRAPHADV_API_KEY;

type Firm = {
  legal_name: string;
  sec_number: string;
  region: string;
  aum_total_usd: number;
};

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

const { data: firms } = (await response.json()) as { data: Firm[] };

Response Format

All responses are returned in JSON format with a wrapper and an optional total count:

{
  "data": [
    {
      "legal_name": "Example Capital Management, LLC",
      "sec_number": "801-123456",
      "region": "Northeast",
      "strategy_class_primary": "HEDGE_FUND",
      "aum_total_usd": 5000000000,
      "employee_count_total": 25
    }
  ],
  "total_count": 1234
}

Common Query Patterns

Filter Funds With Assets Greater Than $1B

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"],
    "filters": { "gross_asset_value_usd": "gte.1000000000" },
    "order": ["gross_asset_value_usd.desc","fund_name.asc"],
    "limit": 25
  }'

Python

large_funds = requests.post(
    f"{BASE_URL}/funds",
    headers=headers,
    json={
        "select": ["fund_business_key", "fund_name", "fund_type_label", "gross_asset_value_usd"],
        "filters": {"gross_asset_value_usd": "gte.1000000000"},
        "order": ["gross_asset_value_usd.desc", "fund_name.asc"],
    },
).json()["data"]

JavaScript

const largeFundsResponse = await fetch(`${BASE_URL}/funds`, {
  method: 'POST',
  headers: { 'x-api-key': GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['fund_business_key', 'fund_name', 'fund_type_label', 'gross_asset_value_usd'],
    filters: { gross_asset_value_usd: 'gte.1000000000' },
    order: ['gross_asset_value_usd.desc', 'fund_name.asc']
  })
});
const { data: largeFunds } = await largeFundsResponse.json();

TypeScript

const largeFundsResponse = await fetch(`${BASE_URL}/funds`, {
  method: 'POST',
  headers: { 'x-api-key': GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['fund_business_key', 'fund_name', 'fund_type_label', 'gross_asset_value_usd'],
    filters: { gross_asset_value_usd: 'gte.1000000000' },
    order: ['gross_asset_value_usd.desc', 'fund_name.asc']
  })
});
const { data: largeFunds } = (await largeFundsResponse.json()) as { data: unknown[] };

Find Firms By Name Pattern

cURL

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

Python

firms = requests.post(
    f"{BASE_URL}/firms",
    headers=headers,
    json={
        "select": ["legal_name", "region", "sec_number"],
        "filters": {"legal_name": "ilike.*Capital*"},
        "order": "legal_name.asc",
    },
).json()["data"]

JavaScript

const firmsResponse = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'region', 'sec_number'],
    filters: { legal_name: 'ilike.*Capital*' },
    order: 'legal_name.asc'
  })
});
const { data: firms } = await firmsResponse.json();

TypeScript

const firmsResponse = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'region', 'sec_number'],
    filters: { legal_name: 'ilike.*Capital*' },
    order: 'legal_name.asc'
  })
});
const { data: firms } = (await firmsResponse.json()) as { data: unknown[] };

Sort Funds By Asset Value

cURL

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

Python

sorted_funds = requests.post(
    f"{BASE_URL}/funds",
    headers=headers,
    json={
        "select": ["fund_name", "fund_type_label", "gross_asset_value_usd"],
        "order": "gross_asset_value_usd.desc",
        "limit": 10,
    },
).json()["data"]

JavaScript

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

TypeScript

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

Paginate Results

Use limit (max 50) to size each page. The proxy returns a total_count value when available so you can calculate how many pages you need. Offset-based pagination is not exposed; prefer ordered pagination by a stable field (e.g., order: "filing_date.desc") combined with filters (e.g., filing_date: "lt.2024-09-01").

API Credits

Each returned record consumes 1 credit. Validated person rows cost 5 credits.

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"],
    "order": "aum_total_usd.desc",
    "limit": 20
  }'

Python

page = requests.post(
    f"{BASE_URL}/firms",
    headers=headers,
    json={"select": ["legal_name", "sec_number", "aum_total_usd"], "order": "aum_total_usd.desc", "limit": 20},
).json()
firms_page = page["data"]
total_records = page.get("total_count")

JavaScript

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

TypeScript

const pageTwoResponse = await fetch(`${BASE_URL}/firms`, {
  method: 'POST',
  headers: { 'x-api-key': GRAPHADV_API_KEY ?? '', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    select: ['legal_name', 'sec_number', 'aum_total_usd'],
    order: 'aum_total_usd.desc',
    limit: 20
  })
});
const { data: pageTwo, total_count } = (await pageTwoResponse.json()) as { data: unknown[]; total_count: number };

Credit Usage

• Every record returned costs 1 credit.
• Records that include revealed contact signals (email, LinkedIn, phone) cost 5 credits when the email is validated; 1 credit otherwise.

Next Steps

Now that you’ve made your first request, explore:

• API Reference - Detailed endpoint documentation
• Examples - Real-world use cases and patterns
• Pagination - Guidance for pulling large result sets

Troubleshooting

401 Unauthorized: Check that your API key is correct and properly formatted in the headers.

404 Not Found: Verify the endpoint URL and entity name are correct.

400 Bad Request: Review your filters, select list, and order clause for typos or unsupported fields.