API & MCP Docs

Endpoints

Authentication

All API requests require a Bearer token. Sign up free at agentdata.run/signup to get your API key.

curl https://agentdata.run/api/v1/lookup?domain=stripe.com \
  -H "Authorization: Bearer YOUR_API_KEY"

Email Filtering

The /v1/lookup endpoint returns every address we found at the domain with its verification_status (valid, catch-all, unverified, unknown). Free provider emails (Gmail, Yahoo, etc.) and addresses that failed verification are always excluded. By default, only emails with confidence ≥ 50 are returned; pass verification_status=valid,catch-all for SMTP-verified only.

# Only outreach-safe emails (confidence 90+, verified or catch-all)
curl "https://agentdata.run/api/v1/lookup?domain=stripe.com&min_confidence=90&verification_status=valid,catch-all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Email Verification

Verification runs continuously against the receiving mail server; the status and the date it was checked come back with each address, so filter on it rather than assuming. Free provider emails (Gmail, Yahoo, Hotmail) are excluded from all responses.

Invalid and disposable emails are filtered out by default (confidence below 50). Emails are re-verified every 30-90 days.

Limits

Three dials per tier. Company, tech stack and signal endpoints work without a key on the per-IP limits; a free key moves you to the account limits and unlocks contacts. Limits exist to stop bulk extraction, not to meter normal use; almost nobody meets them.

The 5-hour window is fixed (it resets on the clock, see X-RateLimit-Reset); companies and contacts reset at midnight UTC. One bucket per account across the website, the API and the MCP server. A 429 carries Retry-After and a reason of rps, req5h, companies_day or contacts_day.

What counts as a contact reveal

Only endpoints that return emails or people charge reveals: one per company, and contact reveals reset at midnight UTC; a company you have already revealed stays open for 30 days without using another.

• /v1/lookup — 1 reveal per domain (emails and people included). An unknown domain is queued for crawling, answers 404 with Retry-After, and is not charged.
• /v1/people, /v1/people/{id}, /v1/career-moves — 1 reveal per company in the response. Results are capped to your remaining reveals.
• /v1/companies, /v1/search, /v1/tech, /v1/tech/{slug}, /v1/signals — no reveals. They count against the request window and the distinct-companies dial, and work without a key.
• /v1/me, /v1/api-key/regenerate — free, not counted.

Fair use: the site and the API share one set of limits per account (per IP without one): 5,000 requests every 5 hours and 5,000 distinct companies a day on a free key, 25,000 and 25,000 on Pro; without a key 300 requests and 200 companies. Up to 50 domains a day can be pushed to the front of the crawl (500 on Pro); more still queue, at normal priority. New free accounts start at 100 reveals a day for their first week when several are created from one address. Accounts used to copy the database in bulk are closed.

Response Headers

All data endpoints return usage headers so you can track consumption programmatically.

Example: /v1/lookup

Full company enrichment in a single call.

curl https://agentdata.run/api/v1/lookup?domain=stripe.com \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "domain": "stripe.com",
  "company": {
    "name": "Stripe",
    "description": "Financial infrastructure for the internet",
    "sector": "Financial Services & Fintech",
    "vertical": "Payments",
    "b2b_b2c": "b2b",
    "business_model": "saas",
    "sales_motion": "plg",
    "size": "large",
    "founded_year": 2010,
    "headquarters_city": "San Francisco",
    "headquarters_country": "US",
    "employee_count": 8000,
    "linkedin": "https://linkedin.com/company/stripe",
    "email_pattern": "first.last",
    "is_catch_all": false,
    "mx_provider": "google-workspace",
    "signals": {
      "has_pricing_page": true,
      "has_api_docs": true,
      "has_blog": true,
      "has_careers_page": true
    }
  },
  "emails": {
    "data": [
      {
        "email": "jane.smith@stripe.com",
        "name": "Jane Smith",
        "title": "VP Engineering",
        "confidence": 95,
        "verification_status": "valid",
        "verified_at": "2026-04-14T10:30:00Z",
        "source": "found",
        "found_on_url": "https://stripe.com/about",
        "found_at": "2026-03-02T08:12:00Z",
        "is_role_based": false
      }
    ],
    "total": 42,
    "verified": 38,
    "returned": 10,
    "capped": true
  },
  "technologies": [
    { "name": "React", "category": "Framework", "confidence": "high" }
  ],
  "people": {
    "data": [
      { "id": "...", "name": "...", "title": "CTO", "seniority": "c_level" }
    ],
    "total": 156,
    "returned": 10,
    "capped": true
  },
  "lookup": {
    "consumed": true,
    "remaining": 249,
    "cached_until": null
  }
}

Error Codes

MCP Server

Seven tools for Claude, Claude Code, ChatGPT, Cursor, Windsurf, VS Code or any MCP client. Without a key they give what the public website shows: lookup_company (the public company page), search_companies, find_people (the first 20 matches), get_technologies, get_signals and check_usage. Personal email addresses and full people results (lookup_company with a key, get_person, find_people beyond the first page) need a free key and cost contact reveals. Every response ends with a usage line so the agent can pace itself.

Setup for each client, the tools, limits and privacy: MCP server guide.

Claude Code:

claude mcp add agentdata -- npx -y agentdata-mcp-server --api-key YOUR_API_KEY

Claude Desktop and Cursor (leave out --api-key to run anonymously; VS Code and others: see the MCP server guide):

{
  "mcpServers": {
    "agentdata": {
      "command": "npx",
      "args": ["-y", "agentdata-mcp-server", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Hosted, nothing to install (Streamable HTTP; the header is optional for the keyless tools):

{
  "mcpServers": {
    "agentdata": {
      "url": "https://mcp.agentdata.run/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The MCP server exposes the same email filters, so an agent can ask for outreach-safe addresses:

"Look up stripe.com and only show me email addresses with status valid and confidence above 90"

Source and changelog: github.com/nick-timms/agentdata-mcp-server.