Semantil API

Discover markets, search companies and enrich domains through one stable API.

API navigation

// error reference

Stable problem codes

Errors use application/problem+json. Unknown fields and disallowed capability fields fail closed before data lookup.

Code	Status	Meaning
`invalid_api_key`	401	Provide a valid API key using the Authorization: Bearer header.
`invalid_field`	400	One or more requested fields do not exist.
`field_not_available_for_capability`	400	A known field is not exposed by this capability. Use the domain endpoint for the complete company record.
`unsupported_parameter`	400	The products parameter was removed. Fields no longer have separate prices.
`lead_requires_enrich`	400	Registry and contact fields require explicit enrich=true on a paid account.
`max_credits_exceeded`	400	The requested record and optional lead add-on can cost more than the caller-approved maximum.
`invalid_filter`	400	One or more requested filters are not available in the Semantil catalog.
`invalid_filter_value`	400	A country filter could not be resolved to a canonical country name or ISO code.
`invalid_request`	400	The request parameters could not be parsed.
`invalid_exclude_domains`	400	exclude_domains must be a valid JSON array containing at most 20,000 domains or HTTP(S) URLs.
`upgrade_required`	403	The current plan does not include this operation or field. Open upgrade_url from the response to see the plan that does.
`insufficient_credits`	402	This request needs more credits than remain. Credits renew on usage.resets_at; request fewer rows or upgrade at https://semantil.com/pricing.
`api_key_restricted`	403	This API key is not permitted to perform the requested action. Create a key with the default access at https://semantil.com/api#api-keys.
`access_scope_restricted`	403	The account access does not include this capability, for example semantic search. Contact Semantil to extend the access.
`domain_not_found`	200	Domain lookup and lookalike return found=false and spend no credits when the seed is absent from the Semantil catalog.
`seed_profile_unavailable`	200	The website is present in the Semantil catalog, but similarity search is not currently available for it. No credits are spent.
`no_similar_companies`	200	Lookalike returns found=false and spends no credits when the seed exists but no suitable candidates are available.
`temporarily_unavailable`	503	Similar-company retrieval is temporarily unavailable. Retry the same request.
`unsupported_media_type`	415	POST /api/search requires Content-Type: application/json.
`request_too_large`	413	The JSON request body exceeds the 5 MB limit.
`rate_limited`	429	Too many requests were sent in a short time window. Retry after the seconds in the Retry-After header (also retry_after in the body).
`access_grant_limit`	429	The evaluation access has used its request or credit allowance. Contact Semantil to continue.
`search_capacity_exceeded`	429	Search capacity is temporarily exhausted.
`catalog_generation_mismatch`	409	The catalog changed after a preceding related result. Restart the related analysis from its first request.
`exclusion_filter_mismatch`	503	The search was not returned or charged because exclusion verification detected an inconsistent backend result.
`catalog_refresh_in_progress`	503	The catalog changed during the request. Retry the same operation.
`search_unavailable`	503	The search service is temporarily unavailable.
`search_capability_unavailable`	503	A required search capability is temporarily unavailable.
`search_timeout`	504	The search did not finish within its bounded execution time.
`search_limit_exceeded`	422	The requested search exceeds a bounded engine limit.
`empty_cohort`	422	The requested cohort has no matching companies in the selected scope. Check exact filter values or broaden the cohort.
`search_contract_error`	502	The application generated a request that the search contract rejected.
`search_upstream_error`	502	The search service could not complete the request.
`internal_error`	500	The request failed before completion.