{ "openapi": "3.1.0", "info": { "title": "Bright Data Deep Lookup API", "description": "The Bright Data Deep Lookup API lets you preview, refine, and execute research queries.\nSupports enrichment, cancellation, and exporting results in multiple formats.", "version": "1.0.0" }, "servers": [ { "url": "https://api.brightdata.com/datasets/deep_lookup/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/preview": { "post": { "summary": "Create Preview", "description": "Generate a preview to validate your query.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "examples": [ "Find all AI startups founded after 2020 with more than 50 employees" ] } } } } } } }, "responses": { "200": { "description": "Preview created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewResponse" } } } } } } }, "/preview/{id}": { "get": { "summary": "Get Preview Data", "description": "Retrieve the preview results and metadata.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "examples": [ "dld_meu4lhla1lj08i6p30" ] } } ], "responses": { "200": { "description": "Preview details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPreviewResponse" } } } } } } }, "/enhance_query": { "post": { "summary": "Enhance Query", "description": "Refine your research query with additional requirements.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "examples": [ "Find all AI startups" ] } } } } } } }, "responses": { "200": { "description": "Query enhanced successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnhanceQueryResponse" } } } } } } }, "/trigger": { "post": { "summary": "Trigger Full Request", "description": "Execute the full research based on preview or with detailed specifications.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TriggerFromPreview" }, { "$ref": "#/components/schemas/DirectTriggerWithSpecifications" } ] } } } }, "responses": { "200": { "description": "Research triggered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } } } } }, "/request/{id}/status": { "get": { "summary": "Get Request Status", "description": "Check the status of your research request.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] } } ], "responses": { "200": { "description": "Request status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatusResponse" } } } } } } }, "/request/{id}": { "get": { "summary": "Get Request Data", "description": "Retrieve the full results of your research.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] } } ], "responses": { "200": { "description": "Request data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestDataResponse" } } } } } } }, "/request/{id}/enrich": { "post": { "summary": "Enrich Column", "description": "Add additional data columns to existing results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "column_name": { "type": "string", "examples": [ "cto_name" ] }, "query": { "type": "string", "examples": [ "CTO or head of engineering name" ] } } } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] } } ], "responses": { "200": { "description": "Enrichment triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } } } } }, "/request/{id}/cancel": { "post": { "summary": "Cancel Request", "description": "Cancel an in-progress research request.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] } } ], "responses": { "200": { "description": "Request cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelResponse" } } } } } } }, "/request/{id}/download": { "get": { "summary": "Download Results", "description": "Export results in JSON, CSV, or Excel.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] } }, { "in": "query", "name": "format", "description": "**Note:** Excel format is not currently available.", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json", "examples": [ "csv" ] } } ], "responses": { "200": { "description": "File download", "content": { "application/json": {} } } } } } }, "components": { "schemas": { "PreviewResponse": { "type": "object", "properties": { "preview_id": { "type": "string", "examples": [ "dld_meu4lhla1lj08i6p30" ] }, "columns": { "type": "array", "items": { "type": "object" }, "examples": [ [ { "company_name": "Anthropic", "website": "anthropic.com", "founded_year": 2021, "employee_count": 160 } ] ] } } }, "GetPreviewResponse": { "type": "object", "properties": { "preview_id": { "type": "string", "examples": [ "dld_meu4lhla1lj08i6p30" ] }, "query": { "type": "string", "examples": [ "Find all AI startups founded after 2020 with more than 50 employees" ] }, "status": { "type": "string", "description": "- `queued` - Request is waiting to be processed\n- `running` - Preview is being generated\n- `completed` - Results ready\n- `failed` - Error occurred", "enum": [ "pending", "processing", "completed", "failed" ], "examples": [ "completed" ] }, "sample_data": { "type": "array", "items": { "type": "object" }, "examples": [ { "company_name": "Anthropic", "website": "anthropic.com", "founded_year": 2021, "employee_count": 160 } ] }, "columns": { "type": "array", "items": { "type": "object" }, "examples": [ [ { "company_name": "Anthropic", "website": "anthropic.com", "founded_year": 2021, "employee_count": 160 } ] ] }, "result_limit": { "type": "integer", "examples": [ 10 ] } } }, "EnhanceQueryResponse": { "type": "object", "properties": { "enhanced_query": { "type": "string", "examples": [ "Find all AI startups in United States that raised Series A funding or later with headquarters in major tech hubs" ] } } }, "TriggerFromPreview": { "type": "array", "items": { "type": "object", "required": [ "preview_id" ], "properties": { "preview_id": { "type": "string", "description": "ID of the preview request to trigger", "examples": [ "dld_meu4lhla1lj08i6p30" ] }, "result_limit": { "type": "integer", "description": "Limit the number of results returned", "examples": [ 100 ] } } } }, "DirectTriggerWithSpecifications": { "type": "array", "items": { "type": "object", "required": [ "query", "spec" ], "properties": { "query": { "type": "string", "description": "High-level query for the research", "examples": [ "Find all AI startups in Israel" ] }, "spec": { "type": "object", "required": [ "name", "query", "title", "columns" ], "properties": { "name": { "type": "string", "examples": [ "companies" ] }, "query": { "type": "string", "examples": [ "Find all startups developing AI products in Israel" ] }, "title": { "type": "string", "examples": [ "AI startups in Israel" ] }, "columns": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "type" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "enrichment", "constraint" ] } } }, "examples": [ { "name": "founding_date", "description": "Founding date of the company", "type": "enrichment" }, { "name": "is_startup_check", "description": "Company must be a startup (early-stage company, typically privately held and recently founded)", "type": "constraint" }, { "name": "employee_count", "description": "Number of employees", "type": "enrichment" } ] } } }, "result_limit": { "type": "integer", "description": "Limit the number of results returned", "examples": [ 50 ] } } } }, "TriggerResponse": { "type": "object", "properties": { "request_id": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] }, "status": { "type": "string", "description": "- `queued` - Request is waiting to be processed\n- `running` - Research in progress", "enum": [ "queued", "running" ], "examples": [ "queued" ] }, "max_cost": { "type": "string", "example": "$50.00" } } }, "RequestStatusResponse": { "type": "object", "properties": { "request_id": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] }, "status": { "type": "string", "description": "- `queued` - Request is waiting to be processed\n- `running` - Research in progress\n- `completed` - Results ready\n- `failed` - Error occurred\n- `cancelled` - Request was cancelled", "enum": [ "queued", "running", "completed", "failed", "cancelled" ], "examples": [ "running" ] }, "progress": { "type": "integer", "description": "Progress percentage (0-100)", "examples": [ 65 ] }, "pages_read": { "type": "integer", "examples": [ 342 ] }, "pages_considered": { "type": "integer", "examples": [ 1250 ] }, "matched_records": { "type": "integer", "examples": [ 31 ] }, "is_trial": { "type": "boolean", "examples": [ false ] }, "result_limit": { "type": "integer", "examples": [ 50 ] } } }, "RequestDataResponse": { "type": "object", "properties": { "request_id": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] }, "query": { "type": "string", "examples": [ "Find all AI startups in Israel" ] }, "status": { "type": "string", "examples": [ "completed" ] }, "title": { "type": "string", "examples": [ "AI startups in Isreal" ] }, "step": { "type": "string", "description": "- `identifying` - Understanding and analyzing the query\n- `generating_schema` - Creating the data structure\n- `generating` - Collecting and processing data\n- `done` - Research completed", "examples": [ "done" ] }, "matched_records": { "type": "integer", "examples": [ 73 ] }, "skipped_records": { "type": "integer", "description": "**Note:** `skipped_records` indicates entities that didn't match filter criteria", "examples": [ 27 ] }, "pages_read": { "type": "integer", "examples": [ 892 ] }, "pages_considered": { "type": "integer", "examples": [ 3421 ] }, "total_cost": { "type": "string", "description": "**Note:** `total_cost` shows current cost (for running requests, this reflects collected records so far)", "examples": [ "$73.00" ] }, "columns": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "type" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "enrichment", "constraint" ] } } }, "examples": [ [ { "name": "company_name", "description": "Company name", "type": "enrichment" } ] ] }, "data": { "type": "array", "items": { "type": "object" }, "examples": [ [ { "company_name": "Run:ai", "website": "run.ai", "founding_date": "2018", "employee_count": 120 } ] ] } } }, "EnrichResponse": { "type": "object", "properties": { "column_name": { "type": "string", "examples": [ "cto_name" ] }, "status": { "type": "string", "description": "- `processing` - Enrichment in progress\n- `completed` - Enrichment finished", "enum": [ "processing", "completed" ], "examples": [ "processing" ] }, "max_additional_cost": { "type": "string", "description": "**Note:** `max_additional_cost` shows the maximum possible cost. Final cost is calculated based only on matched records.", "examples": [ "$3.65" ] } } }, "CancelResponse": { "type": "object", "properties": { "request_id": { "type": "string", "examples": [ "ai_meu3z0171o8k9jc4dh" ] }, "status": { "type": "string", "examples": [ "cancelled" ] }, "records_processed": { "type": "integer", "examples": [ 45 ] }, "charge": { "type": "string", "examples": [ "$45.00" ] } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use your Bright Data API Key as a Bearer token in the Authorization header.\n\n**How to authenticate:**\n1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users\n2. Include the API Key in the Authorization header of your requests\n3. Format: `Authorization: Bearer YOUR_API_KEY`\n\n**Example:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\nLearn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication", "bearerFormat": "API Key" } } } }