> ## Documentation Index > Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search > Search the web, news, images, scholarly papers, companies and people in one call. Send one request and get JSON back. Examples in cURL, TypeScript and Python. Best when you want web results, news, images or all three at once, grouped by type, with the page text of the top web results if you ask for it. Send categories research for scholarly papers with authors, venue and citation counts, companies for company profiles filtered by place, industry, size and founding year, people for people by role, company, place or research topic, or developer for passages from GitHub issues, pull requests, releases, READMEs, developer docs and API operations. > [!NOTE] > > Works without an API key, up to 10 calls a minute and 50 a day per IP. See [Rate limits](https://docs.stophy.dev/rate-limits.md). ## Price 2 credits per 10 results from each source and each research, companies, people or developer list, plus 1 credit for each web result that comes back with its page text when scrapeOptions is on. See [Pricing](https://docs.stophy.dev/billing.md) for what credits cost. ```bash cURL theme={null} curl -X POST https://api.stophy.dev/v1/search \ -H "Authorization: Bearer $STOPHY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"nvidia earnings","sources":["web","news"],"limit":5}' ``` ```typescript TypeScript theme={null} const response = await fetch("https://api.stophy.dev/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "nvidia earnings", sources: ["web", "news"], limit: 5, }), }); console.log(await response.json()); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.stophy.dev/v1/search", headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}, json={ "query": "nvidia earnings", "sources": ["web", "news"], "limit": 5, }, ) print(response.json()) ``` ```json 200 theme={null} { "success": true, "data": { "news": [ { "title": "Stocks making the biggest moves midday: Micron, Tesla, Tripadvisor, AppLovin, Nvidia & more", "url": "https://www.cnbc.com/2026/11/05/stocks-making-the-biggest-moves-midday-mu-tsla-trip-app-nvda.html", "snippet": "Here are some of the companies making headlines in midday trading.", "date": "2026-11-05T18:35:11.000Z", "position": 1 } ], "web": [ { "url": "https://nvidianews.nvidia.com/news/nvidia-announces-financial-results-for-second-quarter-fiscal-2027", "title": "NVIDIA Announces Financial Results for Second Quarter Fiscal ...", "description": "GAAP and non-GAAP earnings per diluted share were $2.46 and $2.22, respectively.\n\n“AI has reached its inflection…", "position": 1 } ] }, "creditsUsed": 4 } ``` ## OpenAPI ````yaml api-reference/openapi.json POST /v1/search openapi: 3.1.0 info: title: Stophy API version: '1' description: >- Every endpoint is a POST that takes its input as a JSON object body. Unknown fields are rejected with 400. Responses leave out empty values: null, empty strings, empty objects and empty nested lists are not sent. Text comes back whole. To get shorter responses, add ?maxTextLength= to the URL. Every text value longer than that is cut and ends with …. A screenshot is never cut, and a page whose text was cut has isTruncated set to true. x-credits is what one call costs. Every call costs the same, whatever it returns, unless an operation's description says it costs per 10 results, or per second of audio. Then x-credits is the lowest price and x-credits-max the most one call can cost. Where an operation takes limit, send it to return fewer results and pay for fewer. When a response has a cursor, send it back unchanged with the same input to get the next page. When it has a page, send the next page number. servers: - url: https://api.stophy.dev security: - apiKey: [] paths: /v1/search: post: summary: >- Search the web, news, images, scholarly papers, companies and people in one call description: >- Costs 2 credits per 10 results from each source and each research, companies, people or developer list, plus 1 credit for each web result that comes back with its page text when scrapeOptions is on. operationId: search parameters: - $ref: '#/components/parameters/MaxTextLength' requestBody: required: true content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 400 sources: description: >- What to search: web, news, images. Each is a string or {type}. Default web, or none when categories asks for research, companies, people or developer. minItems: 1 maxItems: 3 type: array items: anyOf: - type: string enum: - web - news - images - type: object properties: type: type: string const: web tbs: type: string location: type: string required: - type additionalProperties: false - type: object properties: type: type: string enum: - news - images required: - type additionalProperties: false categories: description: >- pdf: web results that are PDF files. research: scholarly papers, in a research list, ranked by relevance then citations. companies: companies that match the query, in a companies list, best matches first. The query can name a place, industry, employee count, founding year and funding stage, like fintech startups in Berlin, 50-200 employees. people: people that match the query, in a people list, best matches first. The query can name a role, company, place or research topic, like CFO of Stripe, founders of fintech startups in Berlin, or researchers on CRISPR base editing. Each person has roles, affiliations and public profile links, never contact details. developer: passages from GitHub READMEs, issues, merged pull requests, releases, developer docs and API operations, in a developer list; send it as an object to filter by repos, types, language and minStars. type: array items: anyOf: - type: string enum: - developer - gov - research - pdf - companies - people - type: object properties: type: type: string enum: - developer - gov - research - pdf - companies - people required: - type additionalProperties: false - type: object properties: type: type: string const: developer repos: default: [] description: >- Only results from these GitHub repositories, as owner/name. maxItems: 5 type: array items: type: string pattern: ^[\w.-]+\/[\w.-]+$ types: default: [] description: >- Only these result types: readme, issue, pull_request, release, operation, doc. type: array items: type: string enum: - readme - issue - pull_request - release - operation - doc language: description: >- Only repositories whose main language is this, like TypeScript. type: string minLength: 1 minStars: description: >- Only repositories with at least this many GitHub stars. type: integer minimum: 0 maximum: 9007199254740991 required: - type additionalProperties: false maxAge: description: >- Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 15 minutes for news and 1 hour for web and images. 0 always searches live. type: integer minimum: 0 maximum: 9007199254740991 limit: description: >- Most results to return for each source. Default 10, or 5 with scrapeOptions, which reads at most 5 pages. News returns at most 50. type: integer minimum: 1 maximum: 100 tbs: description: >- Time filter: qdr:h, qdr:d, qdr:w, qdr:m or qdr:y, or cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY. Web takes both; news takes qdr only; images take none. type: string minLength: 1 location: description: >- Where to search from, like Germany or San Francisco,California,United States. The last part is the country and replaces country. A city before it narrows web results to that place. type: string minLength: 1 country: description: >- Two-letter country to search from, like us. Image results are always US. type: string pattern: ^[A-Za-z]{2}$ includeDomains: maxItems: 10 type: array items: type: string excludeDomains: maxItems: 10 type: array items: type: string safe: description: Hide explicit web and image results when true. type: boolean timeout: default: 60000 description: Milliseconds to wait for the sources. type: integer minimum: 1000 maximum: 9007199254740991 ignoreInvalidURLs: default: false description: Leave out results whose address cannot be read as a page. type: boolean highlights: default: true description: >- On by default. When a web result's page is already stored, its description is the passages of that page that best match the query. Send false for the snippet the search engine shows. type: boolean domainTools: type: boolean const: false toolDetail: type: string const: compact enterprise: maxItems: 0 type: array items: type: string threatProtection: type: object properties: {} additionalProperties: {} scrapeOptions: description: >- Reads the top web results, up to 5, and puts the passages that best match the query in each description. Add "markdown" to formats to get the whole page text too. Costs 1 more credit for each page read. type: object properties: formats: type: array items: anyOf: - type: string - type: object properties: type: type: string required: - type onlyMainContent: type: boolean const: true onlyCleanContent: type: boolean const: false includeTags: maxItems: 0 type: array items: type: string excludeTags: maxItems: 0 type: array items: type: string maxAge: type: number const: 172800000 zeroDataRetention: default: false description: >- Send true to keep nothing from the pages read, and read each one live. Costs 1 more credit per page. type: boolean headers: type: object properties: {} additionalProperties: {} waitFor: type: number const: 0 mobile: type: boolean const: false skipTlsVerification: type: boolean const: false timeout: type: number const: 60000 removeBase64Images: type: boolean const: true blockAds: type: boolean const: true proxy: type: string const: auto storeInCache: type: boolean const: true lockdown: type: boolean const: false checkPromptInjection: type: boolean const: false redactPII: type: boolean const: false additionalProperties: false required: - query additionalProperties: false example: query: nvidia earnings sources: - web - news limit: 5 responses: '200': description: The data, and the credits this call used. headers: X-Request-ID: $ref: '#/components/headers/RequestId' x-credits-used: $ref: '#/components/headers/CreditsUsed' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' x-cache: $ref: '#/components/headers/Cache' x-cache-age: $ref: '#/components/headers/CacheAge' content: application/json: schema: type: object additionalProperties: false properties: success: type: boolean const: true data: type: object additionalProperties: false properties: web: type: array items: type: object additionalProperties: false properties: url: type: string title: type: string description: type: string position: type: integer minimum: -9007199254740991 maximum: 9007199254740991 markdown: type: string html: type: string rawHtml: type: string links: type: array items: type: string screenshot: type: string metadata: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/search.schema0' scrapeError: type: string required: - position news: type: array items: type: object additionalProperties: false properties: url: type: string title: type: string snippet: type: string date: type: string imageUrl: type: string position: type: integer minimum: -9007199254740991 maximum: 9007199254740991 markdown: type: string html: type: string rawHtml: type: string links: type: array items: type: string screenshot: type: string metadata: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/search.schema0' scrapeError: type: string required: - position images: type: array items: type: object additionalProperties: false properties: url: type: string imageUrl: type: string imageWidth: type: integer minimum: -9007199254740991 maximum: 9007199254740991 imageHeight: type: integer minimum: -9007199254740991 maximum: 9007199254740991 position: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - position research: type: array items: type: object additionalProperties: false properties: title: type: string url: type: string format: uri description: >- The paper's DOI link, or its OpenAlex page when it has no DOI. doi: type: string snippet: description: >- The part of the abstract that best matches the query. type: string authors: type: array items: type: string description: Up to the first 10 authors. year: type: integer minimum: -9007199254740991 maximum: 9007199254740991 venue: description: The journal, conference or repository. type: string type: description: >- article, preprint, review, book-chapter and so on. type: string citedByCount: type: integer minimum: 0 maximum: 9007199254740991 openAccessUrl: description: A free copy of the paper, when one exists. type: string format: uri position: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - url - citedByCount - position companies: type: array items: type: object additionalProperties: false properties: name: type: string legalName: type: string description: type: string website: type: string format: uri domain: type: string linkedinUrl: type: string format: uri industry: type: string size: description: Employee band, like 51-200. type: string employees: description: Exact headcount, when known. type: integer minimum: -9007199254740991 maximum: 9007199254740991 founded: description: Year founded. type: integer minimum: -9007199254740991 maximum: 9007199254740991 incorporated: description: Registry incorporation date. type: string type: description: >- private, public, nonprofit, educational or government_agency. type: string status: description: Registry status, like active. type: string headquarters: type: object additionalProperties: false properties: city: type: string region: type: string country: description: Two-letter country code. type: string address: type: string postcode: type: string required: [] tickers: type: array items: type: string parent: type: object additionalProperties: false properties: name: type: string lei: type: string required: [] revenue: type: object additionalProperties: false properties: amount: type: number currency: type: string required: - amount legalEntities: type: array items: type: object additionalProperties: false properties: name: type: string country: type: string idType: type: string description: >- lei, cik, companyNumber, siren, cnpj, abn, organisationNumber, businessId, registryCode, ico or corporationNumber. id: type: string required: [] description: >- The registered legal entities behind the company, best match first. funding: type: array items: type: object additionalProperties: false properties: stage: type: string amount: type: number currency: type: string date: type: string investors: type: array items: type: string sourceUrl: type: string format: uri required: [] description: Funding rounds, newest first. officers: type: array items: type: object additionalProperties: false properties: name: type: string role: type: string required: [] description: Officers and directors named in public filings. position: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - position people: type: array items: type: object additionalProperties: false properties: name: type: string description: description: A short description of the person. type: string occupations: type: array items: type: string roles: type: array items: type: object additionalProperties: false properties: title: type: string relationships: type: array items: type: string description: >- How the filing describes the role, like Director or Executive Officer. company: type: string startDate: type: string endDate: type: string lastSeen: description: The last filing that names them. type: string source: type: string required: [] description: >- Where they work or have worked. Our sources do not say which is current. affiliations: type: array items: type: object additionalProperties: false properties: institution: type: string city: type: string country: type: string lastYear: type: integer minimum: -9007199254740991 maximum: 9007199254740991 current: type: boolean required: - current description: Research institutions, from author records. topics: type: array items: type: string description: Research topics, for authors. links: type: array items: type: string description: >- Public profile links, like Wikidata, ORCID, SEC and OpenAlex. position: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - position developer: type: array items: type: object additionalProperties: false properties: url: type: string title: type: string description: type: string type: type: string repo: type: string stars: type: integer minimum: -9007199254740991 maximum: 9007199254740991 language: type: string date: type: string state: type: string fixedBy: type: string releasedIn: type: string method: type: string path: type: string product: type: string position: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - position required: [] warning: type: string creditsUsed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - success - creditsUsed 4XX: $ref: '#/components/responses/Error' 5XX: $ref: '#/components/responses/Error' security: - apiKey: [] components: parameters: MaxTextLength: name: maxTextLength in: query required: false description: >- Cut every text value in the response to this many characters. A value that was cut ends with …, and a page whose text was cut has isTruncated set to true. A screenshot is never cut. Leave it out to get the full text. schema: type: integer minimum: 1 headers: RequestId: description: The request id. Quote it when you report a problem. schema: type: string CreditsUsed: description: Credits this call used. schema: type: integer RateLimitLimit: description: Requests allowed in the current window. schema: type: integer RateLimitRemaining: description: Requests left in the current window. schema: type: integer RateLimitReset: description: Unix time in seconds when the current window resets. schema: type: integer Cache: description: hit if this result came from the cache, miss if it was fetched live. schema: type: string CacheAge: description: Seconds since the returned result was written to the cache. schema: type: integer RetryAfter: description: Seconds to wait before retrying. schema: type: integer schemas: search.schema0: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/search.schema0' - type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/search.schema0' Error: type: object required: - success - error - code properties: success: const: false error: type: string description: What went wrong and what to do next. code: type: string enum: - apiKeyRequired - cliSessionCompleted - cliSessionExists - cliSessionNotFound - forbidden - freeLimit - insufficientCredits - internalError - inviteClaimed - inviteDisabled - inviteExpired - inviteUsedUp - invalidCliSession - invalidCliVerifier - invalidRequest - jobFinished - methodNotAllowed - notFound - payloadTooLarge - profileBusy - profileTooLarge - rateLimited - sourceChanged - sourceRefused - siteNotRead - sourceTimeout - sourceUnavailable - unauthorized - unsupportedMediaType retryAfterSeconds: type: integer signupUrl: type: string const: https://stophy.dev/signup description: >- Where a person gets a key. Sent with apiKeyRequired, freeLimit and an invalid key. signup: type: string const: POST https://api.stophy.dev/v1/signup description: >- The call that gets an agent a key with no human. Sent next to signupUrl. responses: Error: description: The request failed. Retry-After says when trying again can help. headers: X-Request-ID: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.