# FAQs - Frequently Asked Questions ## Access - [How do I authenticate and generate API tokens?](#how-do-i-authenticate-and-generate-api-tokens) - [Is my API key tied to my user account or my org?](#is-my-api-key-tied-to-my-user-account-or-my-org) - [Do I need a subscription to use the API?](#do-i-need-a-subscription-to-use-the-api) - [Can I test the API before writing any code?](#can-i-test-the-api-before-writing-any-code) - [Why am I getting a 401 on a field group?](#why-am-i-getting-a-401-on-a-field-group) ## Credits - [How do credits work?](#how-do-credits-work) - [Do I get charged if no data is returned?](#do-i-get-charged-if-no-data-is-returned) - [How do I check my credit balance?](#how-do-i-check-my-credit-balance) ## Documentation and Data - [Where can I view detailed API documentation, field lists, and example requests/responses?](#where-can-i-view-detailed-api-documentation-field-lists-and-example-requestsresponses) - [What data fields and objects are available for export through the API?](#what-data-fields-and-objects-are-available-for-export-through-the-api) ## Making Requests - [How many companies can I enrich in one request?](#how-many-companies-can-i-enrich-in-one-request) - [Is bulk export supported? What's the maximum batch size?](#is-bulk-export-supported-whats-the-maximum-batch-size) - [What's the difference between Company Search and Company Match?](#whats-the-difference-between-company-search-and-company-match) - [Can I preview the cost of a request before running it?](#can-i-preview-the-cost-of-a-request-before-running-it) - [Are there best practices for handling large data sets and optimizing data pulls via the API?](#are-there-best-practices-for-handling-large-data-sets-and-optimizing-data-pulls-via-the-api) ## Rate Limits - [What are the rate limits (requests per minute/hour/day) for the API?](#what-are-the-rate-limits-requests-per-minutehourday-for-the-api) - [Are there timeouts or restrictions on consecutive API batch pulls?](#are-there-timeouts-or-restrictions-on-consecutive-api-batch-pulls) - [What happens if I exceed the rate limit?](#what-happens-if-i-exceed-the-rate-limit) ## Errors and Troubleshooting - [What does this error mean?](#what-does-this-error-mean) - [Why am I getting a 422?](#why-am-i-getting-a-422) - [Why is a company returning no data?](#why-is-a-company-returning-no-data) ## Platform vs API vs MCP - [Can segments created in the UI be accessed and exported programmatically via the API?](#can-segments-created-in-the-ui-be-accessed-and-exported-programmatically-via-the-api) - [Is there a difference in API capabilities or limits between the main platform and MCP?](#is-there-a-difference-in-api-capabilities-or-limits-between-the-main-platform-and-mcp) ## Need Help - [Can I ask Claude to help me write the right API request?](#can-i-ask-claude-to-help-me-write-the-right-api-request) - [Who can I contact for support if I encounter issues or need higher volume access?](#who-can-i-contact-for-support-if-i-encounter-issues-or-need-higher-volume-access) ### How do I authenticate and generate API tokens? Log in to [admin.hginsights.com](https://admin.hginsights.com) as an admin, go to **Settings** > **API Keys**, and click **Create API Key**. API keys start with `hg_v2_`. To authenticate, include your key in the `Authorization` header of every request as a Bearer token: `Authorization: Bearer YOUR_API_KEY`. See [Authentication](/v2/guides/authentication). ### Is my API key tied to my user account or my org? Your org, not an individual user. API access is API-key based and managed at the org level — so if the person who created the key leaves, the key stays active and doesn't get deactivated. ### Do I need a subscription to use the API? Yes. You need an active subscription to HG Insights with credits included. If you don't have one, contact your account manager or reach out at [hginsights.com](https://hginsights.com). ### Can I test the API before writing any code? Yes — use the **Try it** button on any endpoint in the [API Reference](/v2/openapi), or follow the [Quickstart](/v2/guides/test-api-key) to make your first call with curl in under two minutes. ### Why am I getting a 401 on a field group? The data returned by `/companies/enrich` depends on your plan's entitlements — you can only request field groups included in your subscription. Contact your account manager to add access, or remove the restricted field group from your request. See [Error Handling](/v2/guides/error-handling). ### How do credits work? Credits are based on what data is returned, not the number of requests. You're only charged the first time you enrich a company within your 12-month contract period — re-enriching the same company is free, with one exception: `/intent/enrich` charges credits on every call since intent data changes frequently. See [Credits and Usage](/v2/guides/credits-and-usage). ### Do I get charged if no data is returned? No. Since credits are based on what data is returned, if a request finds nothing for a company, you're not charged for it. See [Credits and Usage](/v2/guides/credits-and-usage#how-credits-work). ### How do I check my credit balance? Call `GET /data-api/v2/credits`, or check the Credit Dashboard in the [HG Admin Portal](https://admin.hginsights.com) under **Settings** > **Credits Usage**. See [Credits and Usage](/v2/guides/credits-and-usage#checking-your-balance). ### Where can I view detailed API documentation, field lists, and example requests/responses? The full [API Reference](/v2/openapi) documents every endpoint, parameter, and response schema, with a live Try-it console and example requests/responses on each operation. ### What data fields and objects are available for export through the API? `/companies/enrich` returns firmographics, technographics, spend, AI spend, AI maturity, cloud maturity, contracts, mentions, statistics, and market benchmarks — request only the field groups you need. Intent signals, corporate hierarchy, functional area intelligence, contracts, and contacts are available through their own dedicated endpoints. See [Understanding HG Data](/v2/guides/understanding-hg-data) for what each category contains, or the full field group table in [Enrich Companies](/v2/guides/enrichment#field-groups). ### How many companies can I enrich in one request? Up to 25 per call to `/companies/enrich` or `/companies/score`. For larger datasets, batch in groups of 25 — see [Bulk Enrich Companies](/v2/guides/bulk-enrichment). ### Is bulk export supported? What's the maximum batch size? Yes. `/companies/enrich` and `/companies/score` accept up to 25 companies per request. For larger lists, split into batches of 25 — see [Bulk Enrich Companies](/v2/guides/bulk-enrichment). ### What's the difference between Company Search and Company Match? **Match** resolves companies you already know (by name, domain, or country) into HG IDs — up to 10 per request. **Search** discovers companies you don't already know using filters like industry, tech stack, or spend. See [Search or Match Companies](/v2/guides/find-companies). ### Can I preview the cost of a request before running it? Yes. Most endpoints that consume credits have a matching `/estimate` endpoint — send the same request body and get back the credit cost without consuming credits or returning data. See [Credits and Usage](/v2/guides/credits-and-usage#estimating-cost-before-you-call). ### Are there best practices for handling large data sets and optimizing data pulls via the API? Batch requests — `/companies/enrich` and `/companies/score` accept up to 25 companies per call, and batching counts as a single request against the rate limit regardless of how many companies you include. For datasets larger than 25, split into batches — see [Bulk Enrich Companies](/v2/guides/bulk-enrichment). Preview credit cost with the `/estimate` endpoints before running large jobs, and implement backoff on `429` responses — see [Rate Limiting](/v2/guides/rate-limiting#best-practices). ### What are the rate limits (requests per minute/hour/day) for the API? It depends on your plan: Sandbox is 2 requests/second and 1,000/day, Standard is 25 requests/second and 50,000/day, and Enterprise is 200 requests/second with no daily cap. See [Rate Limiting](/v2/guides/rate-limiting). ### Are there timeouts or restrictions on consecutive API batch pulls? There's no separate timeout or cooldown on consecutive batch pulls — your plan's per-second limit applies continuously, and the rate limit is per request, not per company. An endpoint that accepts multiple companies per call (e.g., `/companies/enrich` with up to 25 companies) counts as one request, so batching is the most efficient way to run consecutive pulls without hitting the limit. The one fair use limit to know: `/companies/search` caps results at 25,000 per query — use filters to segment larger pulls into multiple queries. See [Rate Limiting](/v2/guides/rate-limiting#how-bulk-endpoints-count) and [Search or Match Companies](/v2/guides/find-companies#pagination). ### What happens if I exceed the rate limit? You'll get a `429 Too Many Requests` response. Check the `x-ratelimit-reset` header to see how long to wait before retrying. See [Rate Limiting](/v2/guides/rate-limiting#rate-limit-headers). ### What does this error mean? All errors follow a consistent structure with a `title`, `detail`, and optional `source.pointer` identifying the problem field. See the full list of HTTP status codes and common error scenarios in [Error Handling](/v2/guides/error-handling). ### Why am I getting a 422? 422 means request validation failed — usually a missing required parameter, an invalid value, or an array exceeding its max size (like more than 25 company IDs). Check `source.pointer` in the error response to find the exact field. See [Error Handling](/v2/guides/error-handling#2-validation-errors-422). ### Why is a company returning no data? Either the company isn't tracked in HG's database, or your filters are too strict. Try loosening your filters, or check your entitlements if you're missing an entire field group. See the [Quickstart troubleshooting section](/v2/guides/test-api-key#troubleshooting). ### Can segments created in the UI be accessed and exported programmatically via the API? Not directly today. Recreate the same filters you'd use in the Platform with `POST /companies/search`, then pass the matching companies to `POST /companies/enrich` for the data you need. Credit cost works the same as it does in the Platform. See [Search or Match Companies](/v2/guides/find-companies) and [Enrich Companies](/v2/guides/enrichment). ### Is there a difference in API capabilities or limits between the main platform and MCP? No — MCP is a wrapper on top of the HG API. When you invoke an MCP tool, it makes the corresponding API request under the hood. The API offers the same search and enrich capabilities available in the Platform. See [Explore the API](/v2/guides/explore-the-api#claude-with-mcp). ### Can I ask Claude to help me write the right API request? Yes. Give Claude (or any LLM) the docs URL or the OpenAPI spec directly, describe what you're trying to do, and it will generate the correct JSON body, curl command, or code in your language. See [Explore the API](/v2/guides/explore-the-api#chatgpt-and-other-llms). ### Who can I contact for support if I encounter issues or need higher volume access? Email [customersupport@hginsights.com](mailto:customersupport@hginsights.com) for support issues, feedback, or data gaps — include the exact request and response so we can reproduce the issue. For higher rate limits or volume needs, contact your HG Insights account manager.