Companies API

Look up a company by domain or slug, fetch many companies in one request, and force a fresh crawl. A company record can carry technographics (the technologies detected on its site), firmographics (industry, size, location), and partnership counts.

All endpoints require an API key — see Authentication — and are credit-metered per company record returned (see Credits).

Get a company

GET /v1/companies/{identifier}

{identifier} is a domain (stripe.com) or a Trace slug (stripe).

Query param	Description
`include`	Comma-separated extras: `technologies`, `firmographics`. Omitted by default.

The base response includes the company’s name, primary_domain, partnership_count, and (when known) slug, domains, and investors. Adding include=technologies attaches a technologies array ordered by global popularity; include=firmographics attaches a firmographics object (industry, employee_range, country, founded_year, tech_count, open_jobs_count, partnership_count).

curl "https://api.tracedata.ai/v1/companies/stripe.com?include=technologies,firmographics" \
  -H "X-API-Key: $TRACE_API_KEY"

{
  "name": "Stripe",
  "primary_domain": "stripe.com",
  "slug": "stripe",
  "partnership_count": 482,
  "domains": ["stripe.com"],
  "firmographics": {
    "industry": "Financial Services",
    "employee_range": "5001-10000",
    "country": "US",
    "founded_year": 2010,
    "tech_count": 87,
    "open_jobs_count": 213,
    "partnership_count": 482
  },
  "technologies": [
    {
      "tech_key": "cloudflare",
      "display_name": "Cloudflare",
      "detection_count": 4,
      "first_seen": "2025-11-02T08:14:00Z",
      "last_seen": "2026-06-18T02:11:00Z"
    }
  ]
}

A missing company returns 404 with error code company_not_found.

Bulk lookup

POST /v1/companies

Look up 1–100 domains in one request. Your key may have a lower batch ceiling; exceeding it returns 400 batch_too_large.

{
  "domains": ["stripe.com", "shopify.com", "notarealdomain.example"],
  "include": ["technologies", "partnerships"]
}

include controls which sections are populated; valid values are technologies, partnerships, and firmographics. Omitted sections come back as empty arrays, which lowers both response size and credit cost.

curl -X POST "https://api.tracedata.ai/v1/companies" \
  -H "X-API-Key: $TRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["stripe.com", "shopify.com"], "include": ["technologies"]}'

{
  "data": [
    {
      "domain": "stripe.com",
      "status": "tracked",
      "company": { "name": "Stripe", "primary_domain": "stripe.com", "slug": "stripe" },
      "technologies": [
        {
          "tech_key": "cloudflare",
          "display_name": "Cloudflare",
          "vendor_name": "Cloudflare",
          "last_seen_at": "2026-06-18T02:11:00Z",
          "evidence_count": 4
        }
      ],
      "partnerships": [],
      "technology_count": 1,
      "partnership_count": 0
    }
  ],
  "total_domains_requested": 2,
  "domains_found": 1,
  "domains_not_found": ["shopify.com"],
  "rejected": 0,
  "rejected_domains": []
}

Each result carries a status of tracked (Trace has data) or not_tracked (the domain isn’t in Trace yet). Malformed domains are dropped into rejected_domains and don’t count toward the batch.

Refresh and poll

POST /v1/companies/refresh

Forces a fresh crawl of 1–100 domains. This is asynchronous: it returns 202 Accepted with a job_id and a Location header pointing at the polling endpoint.

curl -X POST "https://api.tracedata.ai/v1/companies/refresh" \
  -H "X-API-Key: $TRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["stripe.com"]}'

{ "job_id": "5f1c8e2a-1b34-4d77-9a0c-2e9f4b6d1a23" }

Then poll:

GET /v1/jobs/{job_id}

curl "https://api.tracedata.ai/v1/jobs/5f1c8e2a-1b34-4d77-9a0c-2e9f4b6d1a23" \
  -H "X-API-Key: $TRACE_API_KEY"

{
  "job_id": "5f1c8e2a-1b34-4d77-9a0c-2e9f4b6d1a23",
  "status": "running",
  "submitted_at": "2026-06-25T16:00:00Z",
  "completed_at": null,
  "summary": { "succeeded": 0, "failed": 0, "processing": 1, "total": 1 },
  "domains": [
    { "domain": "stripe.com", "status": "processing", "error": null }
  ]
}

status is running until every domain reaches a terminal state, then completed (or failed). While running, the response carries a Retry-After: 60 header — wait that long between polls. Once any domain succeeds, the response adds a data_freshness note: detection data is applied immediately, but the derived technology/firmographic views can take up to about an hour to reflect it. A job_id that isn’t yours (or doesn’t exist) returns 404 job_not_found.

List and search companies

GET /v1/companies

Query param	Description
`q`	Text search over company name
`partner_with`	Filter to companies partnering with this slug/domain
`partnership_types`	Comma-separated: `technology`, `channel`, `generic`
`partner_count_min` / `partner_count_max`	Filter by partner count
`has_partner_page`	`true`/`false` — has a discovered partner page
`sort`	`partnership_count` or `name`; prefix `-` for descending (default `-partnership_count`)
`page`, `limit`	Pagination (`limit` max 100)
`include`	`firmographics` to attach the firmographics object to each row

Returns the standard paginated envelope (data + pagination) described in the overview.