API & MCP Docs

Endpoints

Authentication

Send your API key as a Bearer token. Every account has one; find it in your account settings. Company, technology and signal endpoints also answer without a key, on the per-IP limits below.

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 keyon the per-IP limits; a key moves you to your account's limits. 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 look-up limits reset at midnight UTC; a company you already looked up today doesn't count again.

• /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}: 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: not counted.

Fair use: the website, the API and the MCP server share one set of limits per account (per IP without one): 50 companies a day without an account, 100 on an account without a plan, 1,000 on Pro and 5,000 on Business. Paging through a customer list you have unlocked counts as requests, not as companies looked up. Up to 50 domains a day can be pushed to the front of the crawl (500 on Pro); more still queue, at normal priority. Accounts used to copy the database in bulk, or shared outside the users a plan includes, 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

Customer lists, new customers and company look-ups in Claude, Claude Code, ChatGPT, Cursor, VS Code or any MCP client, with your AgentData account and its plan's limits. Claude and ChatGPT connect by signing in or pasting your API key; other clients send the key as a header.

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

Hosted (Streamable HTTP):

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

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