{"uid":"cap_TNKxXdNvZoND7W50ZNiNv","slug":"beliefstate-entity-search-88e23c58","name":"BeliefState Entity Search","description":"The first AI-powered platform for top analyst research. Get theses from top analysts, dated evidence, and available outcomes for your AI.","url":"https://beliefstate.ai/v1/research/search_entities?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input","output"],"properties":{"input":{"type":"object","required":["type","method","bodyType","body"],"properties":{"body":{"type":"object","properties":{"q":{"type":"string","maxLength":80,"minLength":1},"kind":{"enum":["company","instrument","commodity","macro_variable","industry","sector","theme","country","geography","person","policy","event_series","event_occurrence","currency","index"],"type":"string"},"as_of":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"limit":{"type":"integer","maximum":50,"minimum":1},"cursor":{"type":"string","maxLength":2048,"minLength":1}},"additionalProperties":false},"type":{"type":"string","const":"http"},"method":{"type":"string","const":"POST"},"bodyType":{"type":"string","const":"json"}},"additionalProperties":false},"output":{"type":"object","required":["type","example"],"properties":{"type":{"type":"string","const":"json"},"example":{"type":"object","$comment":"Envelope excerpt only. Complete response schema: https://beliefstate.ai/v1/research/search_entities?schema=output","required":["schema_version","generated_at","as_of"],"properties":{"as_of":{"type":"string","format":"date-time"},"generated_at":{"type":"string","format":"date-time"},"schema_version":{"type":"string","const":"1"}}}}}}},"responseSchema":{"type":"json","example":{"as_of":"2026-10-24T00:00:00.000Z","generated_at":"2026-10-24T00:00:00.000Z","schema_version":"1"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.02","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.02/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_hDTLh_u6hF1CTCJxrFr1M","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.02","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Search and resolve financial/economic entities (companies, instruments, sectors, themes, etc.) by name or keyword for use in analyst research lookups","exampleAgentPrompt":"Search BeliefState for a 'company' entity matching 'Nvidia' as of today and return up to 10 results so I can find the right entity ID before pulling analyst research on it.","exampleUseCases":[{"title":"Resolve company before pulling analyst theses","prompt":"Search BeliefState for a company entity called 'Tesla' — I want to find the right entity ID so I can then pull analyst research and investment theses about it. Give me up to 5 results."},{"title":"Identify macro variable entity for AI model","prompt":"I need to look up a macro variable entity for 'US unemployment rate' on BeliefState — search for it with kind set to macro_variable and return up to 10 matches so my trading agent can reference the correct one."},{"title":"Find sector entity for thematic research","prompt":"Can you search BeliefState for a 'sector' entity matching 'semiconductors'? Limit it to 5 results and use today's date as the as-of timestamp — I want to find the right entity before fetching analyst coverage."}],"resultDescription":"A paginated JSON envelope (schema_version '1') containing matched entity records relevant to the search query, along with a generated_at timestamp and an as_of timestamp indicating data currency. The full response schema includes entity details usable in downstream BeliefState research endpoints.","failureModes":["Query string too short (minLength 1) or too long (maxLength 80) returns validation error","Invalid kind enum value causes schema rejection","Malformed as_of datetime (must be ISO 8601 UTC with Z suffix) causes validation error","Limit outside range 1–50 returns validation error","No matching entities found returns empty result set","Payment failure or insufficient USDC balance blocks the request","Invalid or expired cursor causes pagination error"],"whenToPreferThis":"Use this endpoint as the first step in a BeliefState research workflow when you need to resolve a named entity (company, instrument, sector, theme, person, country, commodity, etc.) to a canonical entity ID before fetching analyst theses or research. Prefer this over free-text research queries when the entity is ambiguous or you need to disambiguate between similarly named entities.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-29T12:35:47.893Z","isFirstParty":false,"canonicalSlug":"beliefstate-entity-search-88e23c58"}