API Reference

Authentication

All API requests require a Bearer token in the Authorization header. Create your API key in Account settings.

curl https://cluster.vc/api/v1/companies \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/v1/companies

Search and browse companies. Without a query, returns companies sorted by source diversity then recency.

Query parameters

A q over its length, a list item that is outside its length, blank, or has quotes, backslashes, braces or control characters, or a malformed tld returns 400 INVALID_PARAMS rather than being dropped. Unknown parameters are ignored.

Example request

curl "https://cluster.vc/api/v1/companies?q=acme&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 123,
      "slug": "acme-corp",
      "displayName": "Acme Corp",
      "domain": "acme.com",
      "website": "https://acme.com",
      "country": "US",
      "city": "San Francisco",
      "description": "Developer tools for startups",
      "industry": ["SaaS", "B2B"],
      "regions": ["North America"],
      "fundingTotalUsd": 1500000,
      "firstSeenAt": "2024-01-15T00:00:00Z",
      "lastSignalAt": "2024-03-10T12:00:00Z",
      "sources": ["hn", "producthunt"],
      "signalsCount": 5,
      "freshness": "hot"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "hasMore": true,
    "recency": "30d"
  }
}

GET /api/v1/companies/[id]

Retrieve a single company with its full signal history. Signal detail depends on your plan tier (see Signal Gating).

Path parameters

Merged or renamed companies

When a company is merged into another or renamed, its old ID returns 301 with error code MOVED, a Location header pointing at the current ID, and the current ID in error.successorId. Most HTTP clients follow the redirect; if you store company IDs, replace the old one with successorId.

Example request

curl https://cluster.vc/api/v1/companies/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": 123,
    "slug": "acme-corp",
    "displayName": "Acme Corp",
    "domain": "acme.com",
    "website": "https://acme.com",
    "country": "US",
    "city": "San Francisco",
    "description": "Developer tools for startups",
    "industry": ["SaaS", "B2B"],
    "regions": ["North America"],
    "fundingTotalUsd": 1500000,
    "firstSeenAt": "2024-01-15T00:00:00Z",
    "lastSignalAt": "2024-03-10T12:00:00Z",
    "sources": ["hn", "sec.gov"],
    "signalsCount": 5,
    "freshness": "hot",
    "tags": ["show-hn"],
    "signals": [
      {
        "id": 1,
        "source": "hn",
        "signalType": "launch",
        "title": "Show HN: Acme Corp",
        "sourceUrl": "https://news.ycombinator.com/item?id=12345",
        "fundingAmountUsd": null,
        "fundingStage": null,
        "freshness": "hot",
        "eventDate": "2024-03-10T11:40:00Z",
        "detectedAt": "2024-03-10T12:00:00Z",
        "meta": {
          "points": 145,
          "num_comments": 23
        },
        "gating": null
      },
      {
        "id": 2,
        "source": "sec.gov",
        "signalType": "filing",
        "title": "Form D: Acme Corp",
        "sourceUrl": null,
        "fundingAmountUsd": 1500000,
        "fundingStage": null,
        "freshness": "warm",
        "eventDate": "2024-02-20T00:00:00Z",
        "detectedAt": "2024-02-21T08:00:00Z",
        "meta": {
          "total_offering_amount": 1500000
        },
        "gating": {
          "reason": "plan_detail",
          "fields": ["meta", "fundingStage", "sourceUrl"],
          "availableAt": null
        }
      }
    ]
  }
}

GET /api/v1/signals

Query recent signals across all sources. Returns signals in reverse chronological order. Signals still within your plan's freshness delay are left out until it has passed (a company's detail lists them, with gating.reason: freshness_delay), so every page holds signals you can use.

Query parameters

Example request

curl "https://cluster.vc/api/v1/signals?source=hn&freshness=hot" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": 1,
      "source": "hn",
      "signalType": "launch",
      "title": "Show HN: Acme Corp",
      "sourceUrl": "https://news.ycombinator.com/item?id=12345",
      "fundingAmountUsd": null,
      "fundingStage": null,
      "freshness": "warm",
      "eventDate": "2024-03-10T11:40:00Z",
      "detectedAt": "2024-03-10T12:00:00Z",
      "meta": {
        "points": 145,
        "num_comments": 23
      },
      "gating": null,
      "company": {
        "id": 123,
        "slug": "acme-corp",
        "displayName": "Acme Corp",
        "domain": "acme.com",
        "website": "https://acme.com",
        "country": "US",
        "city": "San Francisco"
      }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "hasMore": true
  }
}

Response Objects

Every field below is always present; a value that is missing or withheld is null. Within v1, fields are only ever added, never removed or renamed, so ignore fields you don't recognise.

Company (search result)

Company (detail): every search result field, plus

Signal

Signal in /api/v1/signals: every Signal field, plus

gating

meta keys by source

meta holds only these keys, and only those with a value. A domain sale's venue is a known marketplace name or "Undisclosed", and a sale price under $2,000 comes as sale_price_under: 2000 instead of sale_price. investors is a list of names. For dates, prefer the signal's eventDate.

Rate Limits

API rate limits are enforced per account (shared by all your API keys) on a daily sliding window. Limits vary by plan. A query (one set of filters, paged with page and page_size) reaches up to the plan's results per query; a page past them returns PAGE_LIMIT_EXCEEDED.

Each plan also has a daily data budget per account, shared with the web app and CSV export. Rows per day counts every list row delivered: /api/v1/companies and /api/v1/signals rows, web search results and CSV rows. Company details count each /api/v1/companies/{id} response and each company page on the web. A page is served in full while rows are left, so the last page of the day may pass the budget by up to one page. Once a budget is spent, requests return 429 ROW_BUDGET_EXCEEDED or DETAIL_BUDGET_EXCEEDED with Retry-After: rows and daily details reset at 00:00 UTC, the weekly details on Monday at 00:00 UTC.

Rate limit headers

Responses to an authenticated request include these headers, errors included. Repeated 429s after the quota runs out, and a 503 when the quota couldn't be checked, may come without them. List responses also carry the RowBudget-* set, company detail responses the DetailBudget-* set (the company details budget that runs out first):

Signal Gating

Signal detail varies by plan. A withheld field is null, and the signal's gating object says why and which fields (see Response Objects). In a company's detail, signals newer than your plan's freshness delay come with freshness_delay and the time detail becomes available, and signals older than your plan's history window (or without a date) come with history_window; /api/v1/signals leaves both out. Detail levels per signal type:

Detail levels by plan

Freshness delay and history window

Errors

All errors return a JSON body with an error object containing a machine-readable code and a human-readable message.

Example error response

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Daily API request limit exceeded. Resets in 14400 seconds."
  }
}