> ## Documentation Index > Fetch the complete documentation index at: https://bulkgrid.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search web pages, images, or news and optionally crawl source pages > Required permission: search:query (also runs:write when crawl is true). ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/search openapi: 3.0.3 info: title: Bulkgrid API version: 0.4.0 description: >- Search the live web, manage and search indexed content under /index, create crawl and extraction runs, and retrieve results. API keys require the scopes listed for each operation. OAuth connections grant MCP and search access only. servers: - url: https://bulkgrid.com description: Bulkgrid security: - apiKeyAuth: [] - bearerAuth: [] tags: - name: Sources description: Source discovery, subscriptions, and indexing - name: Collections description: Collections and content selection rules - name: Search description: Search endpoints - name: Index description: Search indexed workspace content - name: Runs description: Run creation and lifecycle endpoints - name: Results description: Run result retrieval endpoints paths: /api/v1/search: post: tags: - Search summary: Search web pages, images, or news and optionally crawl source pages description: 'Required permission: search:query (also runs:write when crawl is true).' operationId: search parameters: [] requestBody: required: true content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 500 type: default: web type: string enum: - web - images - news limit: default: 10 type: integer minimum: 1 maximum: 10 country: default: us type: string pattern: ^[a-z]{2}$ language: default: en type: string pattern: ^[a-z]{2,3}(?:-[A-Za-z]{2,4})?$ location: type: string minLength: 1 maxLength: 200 crawl: default: false type: boolean crawlOptions: type: object properties: formats: default: - markdown - cleanHtml type: array items: type: string enum: - markdown - cleanHtml - rawHtml - links includeTags: type: array items: type: string excludeTags: type: array items: type: string waitAfterLoad: default: 0 type: number minimum: 0 maximum: 30000 timeout: default: 30000 type: number minimum: 1000 maximum: 60000 blockAds: default: true type: boolean useInteractions: default: false type: boolean waitForSelector: type: string waitForImages: default: false type: boolean removeConsentPopups: type: boolean screenshot: type: string enum: - screenshot - fullPageScreenshot useHttp: type: boolean useLlmsTxt: type: boolean additionalProperties: false required: - query additionalProperties: false responses: '200': description: Successful response content: application/json: schema: oneOf: - type: object properties: query: type: string count: type: integer minimum: 0 maximum: 9007199254740991 warnings: type: array items: type: string type: type: string enum: - web results: type: array items: type: object properties: url: type: string format: uri title: type: string snippet: type: string position: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - url - title - snippet - position additionalProperties: false run: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string enum: - pending - processing - completed - failed - cancelled required: - id - status additionalProperties: false required: - query - count - type - results - run additionalProperties: false title: WebSearchResponse - type: object properties: query: type: string count: type: integer minimum: 0 maximum: 9007199254740991 warnings: type: array items: type: string type: type: string enum: - images results: type: array items: type: object properties: title: type: string url: type: string format: uri imageUrl: type: string format: uri imageWidth: nullable: true type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 imageHeight: nullable: true type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 thumbnailUrl: nullable: true type: string format: uri position: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - title - url - imageUrl - imageWidth - imageHeight - thumbnailUrl - position additionalProperties: false run: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string enum: - pending - processing - completed - failed - cancelled required: - id - status additionalProperties: false required: - query - count - type - results - run additionalProperties: false title: ImageSearchResponse - type: object properties: query: type: string count: type: integer minimum: 0 maximum: 9007199254740991 warnings: type: array items: type: string type: type: string enum: - news results: type: array items: type: object properties: url: type: string format: uri title: type: string snippet: type: string position: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 source: nullable: true type: string date: nullable: true type: string imageUrl: nullable: true type: string format: uri required: - url - title - snippet - position - source - date - imageUrl additionalProperties: false run: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string enum: - pending - processing - completed - failed - cancelled required: - id - status additionalProperties: false required: - query - count - type - results - run additionalProperties: false title: NewsSearchResponse '400': description: Bad request content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false '403': description: Forbidden content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false '404': description: Not found content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false '429': description: Rate limited content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false '502': description: >- Search provider unavailable, timed out, or returned an invalid response content: application/json: schema: type: object properties: error: type: string details: {} required: - error additionalProperties: false security: - apiKeyAuth: [] - bearerAuth: [] components: securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Bulkgrid API key bearerAuth: type: http scheme: bearer description: >- Bulkgrid API key or OAuth access token. OAuth grants currently allow search:query and mcp:use only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.