Skip to content
Trace API & MCP Docs

REST API overview

The Trace REST API exposes web technology detection and vendor intelligence over plain HTTPS + JSON. Use it to look up a company’s technographics and firmographics, find every company using a given technology or vendor, and walk partnership relationships.

Base URL

Section titled “Base URL”

All endpoints live under the /v1 path on the production host:

https://api.tracedata.ai/v1

Authentication

Section titled “Authentication”

Every /v1 endpoint requires an API key, sent in the X-API-Key header:

Authentication header
X-API-Key: <your-key>

See Authentication for how to mint and rotate keys. Most read endpoints are credit-metered — see Credits & billing for what counts as a billable record.

JSON conventions

Section titled “JSON conventions”

  • Requests and responses are JSON. POST bodies use Content-Type: application/json.

  • Timestamps are ISO 8601 strings (UTC), e.g. 2026-06-01T14:32:00Z. Fields ending in _at carry timestamps.

  • Identifiers. Company endpoints accept either a domain (stripe.com) or a Trace slug (stripe) wherever the path says {identifier}.

  • Pagination. List endpoints take page (1-indexed) and limit query params and return a pagination object:

    {
      "data": [ /* ... */ ],
      "pagination": {
        "page": 1,
        "limit": 50,
        "total_results": 1284,
        "total_pages": 26,
        "has_next": true,
        "has_prev": false,
        "next_url": "https://api.tracedata.ai/v1/...?page=2&limit=50"
      }
    }

    Some endpoints (batch lookup, technology/vendor company lists) use a slightly different envelope — see each endpoint’s page for the exact shape.

  • Errors return a non-2xx status with a JSON error body. See Errors for the catalog of codes.

Async refresh + polling

Section titled “Async refresh + polling”

Most reads are synchronous. The exception is forcing a fresh crawl of one or more domains: POST /v1/companies/refresh is asynchronous. It returns 202 Accepted with a job_id and a Location header, then you poll for completion:

  1. POST /v1/companies/refresh with a list of domains → 202 + { "job_id": "..." }.
  2. GET /v1/jobs/{job_id} → per-domain status until the job reaches a terminal state. While the job is still running the response carries a Retry-After: 60 header.

Detection data from a refresh lands immediately, but the derived technology/firmographic views can take up to about an hour to reflect it. See Companies API → Refresh and poll for the full flow.

Endpoint families

Section titled “Endpoint families”
Family What it does Page
Companies Look up a company by domain/slug, bulk lookup, refresh, list/search Companies API
Data flags Send company data-quality feedback to Trace for review Data flags API
Technologies & vendors Search technologies; find companies using a technology or vendor Technologies & Vendors API
Partnerships Companies partnering with a domain, bilateral lookup, shared partners, graphs Partnerships API
Lists Build and manage saved company lists (user-scoped key) Lists API
Enrichment Batch-enrich partnership data for many domains at once Enrichment API