{ "openapi": "3.0.3", "info": { "title": "Bigdata Search API", "version": "1.0.0", "description": "Easily find the most relevant information from trusted sources and your own data. Use it to power agents that give accurate, real-time answers." }, "servers": [ { "url": "https://api.bigdata.com/" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "DocumentUrlResponse": { "type": "object", "description": "Response containing a presigned URL to access the document content.", "properties": { "url": { "type": "string", "format": "uri", "description": "Presigned URL that provides temporary access to the document content. The URL returns the document in rpjson format.", "example": "https://documents.bigdata.com/documents/776769957735667D2F01F695EF4F1231?signature=abc123..." } }, "required": ["url"] }, "BatchJobStatusResponse": { "properties": { "batch_id": { "type": "string", "title": "Batchid", "description": "The unique identifier for your batch job." }, "status": { "allOf": [ { "$ref": "#/components/schemas/Status" } ], "description": "Current processing state of your batch job. Poll this endpoint until status reaches `completed` or `failed`." }, "output_file_url": { "type": "string", "format": "uri", "nullable": true, "title": "Output File Url", "description": "Presigned URL to download your results. Available only when status is `completed`. Use a simple GET request to download the `.jsonl` results file." } }, "type": "object", "required": [ "batch_id", "status" ], "title": "BatchJobStatusResponse" }, "BatchJobUploadResponse": { "properties": { "batch_id": { "type": "string", "title": "Batchid", "description": "A unique identifier for your batch job. Use this ID to [check the status of your batch](/api-reference/batch-search/get-batch-job-info)." }, "presigned_url": { "type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Presignedurl", "description": "A temporary, secure URL for uploading your input file. Upload your .jsonl file to this URL [using a PUT request](/api-reference/batch-search/upload-your-input-file). Once uploaded, your batch job will begin processing automatically." } }, "type": "object", "required": [ "batch_id", "presigned_url" ], "title": "BatchJobUploadResponse", "example": { "batch_id": "2211478e-45a8-4d2e-ac51-77e25f6f7c79", "presigned_url": "https://s3.amazonaws.com/bucket/file?X-Amz-Algorithm=..." } }, "ErrorResponse": { "properties": { "statusCode": { "type": "integer", "title": "Statuscode" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "statusCode", "message" ], "title": "ErrorResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ], "title": "Status", "description": "Public-facing batch job status values." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "DocumentFromUrl": { "type": "object", "description": "Structure returned when you access the pre-signed URL. Contains the complete document with metadata, content, optional analytics, and optional pipeline version stamps.", "properties": { "document": { "description": "Document metadata including source information, timestamps, and details.", "allOf": [{ "$ref": "#/components/schemas/Document" }] }, "content": { "description": "Document content including title, body blocks, entities, and sentences.", "allOf": [{ "$ref": "#/components/schemas/Content" }] }, "analytics": { "description": "Document-level analytics, detected events, and entity aggregates.", "allOf": [{ "$ref": "#/components/schemas/FetchDocumentAnalytics" }] }, "software_versions": { "description": "Optional collection and enrichment build identifiers.", "allOf": [{ "$ref": "#/components/schemas/SoftwareVersions" }] } }, "required": ["document", "content"] }, "Document": { "type": "object", "description": "Complete document structure returned when accessing the URL. This is the JSON format used by Bigdata.com for structured document representation.", "properties": { "rp_document_id": { "type": "string", "description": "Internal document identifier", "example": "776769957735667D2F01F695EF4F1231" }, "source": { "$ref": "#/components/schemas/DocumentSourceDetails" }, "timestamps_utc": { "$ref": "#/components/schemas/DocumentTimestampsUtc" }, "metadata": { "$ref": "#/components/schemas/DocumentMetadataDetails" } }, "required": ["rp_document_id", "source", "metadata"] }, "Content": { "type": "object", "description": "Structured content extracted from the document including title and body blocks.", "properties": { "stats": { "$ref": "#/components/schemas/ContentStats" }, "title": { "$ref": "#/components/schemas/ContentTitleBlock" }, "body": { "$ref": "#/components/schemas/ContentBodyBlock" } }, "required": ["title", "body"] }, "ContentStats": { "type": "object", "description": "Optional size statistics for the document text payload.", "properties": { "word_count": { "type": "integer", "description": "Approximate word count for indexed body text.", "example": 8481 }, "byte_count": { "type": "integer", "description": "Approximate byte size of the serialized content payload.", "example": 1336670 } } }, "DocumentSourceDetails": { "type": "object", "description": "Information about the document source.", "properties": { "rp_external_source_id": { "type": "string", "description": "External source identifier when the upstream feed exposes one.", "example": "836C09E6173AAA3DA6A1415030B4EC2D" }, "rp_provider_id": { "type": "string", "description": "Short provider code for the originating data partner.", "example": "FSTR" }, "rp_source_id": { "type": "string", "description": "Identifier of the source system", "example": "D4B903" }, "name": { "type": "string", "description": "Source display name for the feed or collection", "example": "Source Name" }, "rank": { "type": "integer", "description": "Ranking classification of the source.", "example": 1 }, "rp_channel_id": { "type": "integer", "description": "Channel identifier when the document is grouped under a provider channel.", "example": 350 } }, "required": ["rp_source_id", "name", "rank"] }, "DocumentTimestampsUtc": { "type": "object", "description": "Pipeline timestamps in UTC for the document record.", "properties": { "published": { "type": "string", "description": "When the provider published or released the underlying asset.", "example": "2026-05-13 18:22:10.000" }, "reception": { "type": "string", "description": "When the document was first received into the collection pipeline.", "example": "2026-05-13 19:05:02.146" }, "analytics": { "type": "string", "description": "When analytics enrichment completed for this revision.", "example": "2026-05-13 19:12:35.698" }, "revision": { "type": "string", "description": "When this metadata revision was materialized.", "example": "2026-05-13 19:12:35.698" } } }, "DocumentRevisionMetadata": { "type": "object", "description": "Provider revision lineage for the document.", "properties": { "chain_id": { "type": "string", "description": "Stable chain identifier for the revision stream (often a provider collection or story id, sometimes with flavor suffixes).", "example": "8821103" }, "sequence_id": { "type": "string", "description": "Monotonic or provider-supplied sequence token within the chain, when present.", "example": "1777297165000" } } }, "DocumentMetadataCollection": { "type": "object", "description": "Link between RavenPack collection identifiers and the provider collection.", "properties": { "rp_collection_id": { "type": "string", "description": "RavenPack collection identifier.", "example": "5ECE52D55DD6708C90A36D1A5B87B518" }, "provider_collection_id": { "type": "string", "description": "Provider-native collection or listing identifier.", "example": "538315" } } }, "TranscriptParticipant": { "type": "object", "description": "Single speaker row from transcript metadata. Field presence varies by role and resolution quality.", "properties": { "id": { "type": "string", "description": "Ordinal id, usually aligned with the map key.", "example": "0" }, "value": { "type": "string", "description": "Display label for the speaker as delivered by the provider.", "example": "Speaker 1 (executive)" }, "type": { "type": "string", "description": "Speaker role class such as operator, corprep, or analyst.", "example": "corprep" }, "title": { "type": "string", "description": "Job title when supplied.", "example": "Chief Financial Officer" }, "entity": { "type": "string", "description": "Provider-side person or role entity identifier when supplied.", "example": "0K7L8M-E" }, "affiliation": { "type": "string", "description": "Employer or desk label as text.", "example": "Example Sensor Corp." }, "affiliation_entity": { "type": "string", "description": "Provider-side identifier for the affiliation organization when distinct from the person entity.", "example": "0G5H6J-E" }, "rp_company_id": { "type": "string", "description": "Resolved RavenPack company identifier when available.", "example": "4ABF38" }, "rp_person_id": { "type": "string", "description": "Resolved RavenPack person identifier when available.", "example": "NSTS71" }, "rp_position_id": { "type": "string", "description": "Resolved standardized position identifier when available.", "example": "8FFEEE" } } }, "DocumentMetadataDetails": { "type": "object", "description": "Provider and RavenPack metadata carried on the document. Fields are sparse: only subsets apply per document type (news, filings, transcripts, web, etc.).", "properties": { "url": { "type": "string", "format": "uri", "description": "URL pointing to the original document or asset when the provider exposes one.", "example": "https://cdn.example.com/provider-assets/transcript.json" }, "provider_document_id": { "type": "string", "description": "Opaque provider document key, often colon-delimited segments (collection, flavor, provider id).", "example": "8821103:CorrectedTranscript:1002003" }, "media_type": { "type": "string", "description": "MIME type of the canonical payload when known.", "example": "application/json" }, "original_language": { "type": "string", "description": "Primary language of the source document.", "example": "en" }, "file_name": { "type": "string", "description": "Original file name for uploaded or file-based documents.", "example": "Weekly summary report.pdf" }, "content_type": { "type": "string", "description": "Legacy or alternate MIME label (for example message/rfc822 for email).", "example": "application/pdf" }, "revision": { "$ref": "#/components/schemas/DocumentRevisionMetadata" }, "transcript_event_date": { "type": "string", "description": "Calendar date of the live session or release for transcript-class documents.", "example": "2026-05-13" }, "transcript_event_datetime": { "type": "string", "description": "Session anchor datetime in the provider or venue timezone context.", "example": "2026-05-13 21:00:00" }, "transcript_event_type": { "type": "string", "description": "Compact code for the session category (for example earnings call).", "example": "EC" }, "transcript_participants": { "type": "object", "description": "Map of string ordinal indexes to participant rows.", "additionalProperties": { "$ref": "#/components/schemas/TranscriptParticipant" } }, "codes": { "type": "array", "description": "Listing, ISIN, or other security codes when supplied.", "items": { "type": "string" }, "example": ["US0000000000"] }, "custom": { "type": "object", "description": "Provider-specific key-value metadata without a fixed cross-provider schema.", "additionalProperties": true }, "reporting_period": { "type": "string", "description": "Fiscal reporting label when the session ties to a reporting window.", "example": "FY-2026-Q4" }, "reporting_start_date_utc": { "type": "string", "description": "Inclusive start of the reporting window in UTC when supplied.", "example": "2026-01-01 00:00:00" }, "reporting_end_date_utc": { "type": "string", "description": "Exclusive or inclusive end of the reporting window in UTC when supplied.", "example": "2026-04-01 00:00:00" }, "reporting_entities": { "type": "array", "description": "Related RavenPack entity identifiers for the reporting view.", "items": { "type": "string" }, "example": ["AEB48D", "RUHOES", "A03871"] }, "collection": { "$ref": "#/components/schemas/DocumentMetadataCollection" }, "provider_primary_entity_id": { "type": "string", "description": "Provider-native primary company identifier for the session.", "example": "19936" }, "provider_primary_entity_name": { "type": "string", "description": "Provider-native primary company display name.", "example": "Example Company Limited" }, "document_type": { "type": "string", "description": "Normalized document flavor (for example transcript-raw, transcript-corrected).", "example": "transcript-raw" } } }, "FetchDocumentAnalyticsDocument": { "type": "object", "description": "Document-level analytics and tone aggregates returned alongside RPJSON.", "properties": { "analytics_version": { "type": "string", "example": "2.0" }, "analytics_revision_number": { "type": "integer", "example": 0 }, "document_type": { "type": "string", "description": "High-level classified document type for analytics.", "example": "TRANSCRIPT-RAW" }, "document_record_count": { "type": "integer", "description": "Count of body records or segments used for analytics.", "example": 257 }, "title_similarity_key": { "type": "string", "description": "Fingerprint linking this title to similar documents.", "example": "0A4AD1E8BF251E1A90E3B2376E471E07" }, "document_sentiment": { "type": "number", "format": "float", "description": "Aggregate document sentiment score.", "example": 0.21 }, "document_sentiment_confidence": { "type": "number", "format": "float", "description": "Confidence for aggregate document sentiment.", "example": 0.65 }, "composite_sentiment_score": { "type": "number", "format": "float", "example": 0.04 }, "sentiment_impact_projection": { "type": "number", "format": "float", "example": -0.2 }, "stock_tone_sentiment": { "type": "integer", "example": 0 }, "earnings_tone_sentiment": { "type": "integer", "example": 0 }, "commentary_sentiment": { "type": "integer", "example": 1 }, "mergers_acquisitions_sentiment": { "type": "integer", "example": 0 }, "corporate_actions_sentiment": { "type": "integer", "example": 0 }, "earnings_release_sentiment": { "type": "integer", "example": 0 }, "product_key": { "type": "string", "example": "EDGE" }, "realtime": { "type": "string", "description": "Flag indicating whether the document was processed under realtime constraints.", "example": "Y" } } }, "FetchDocumentAnalyticsEventRole": { "type": "object", "description": "Per-entity role inside a detected document event.", "properties": { "rp_entity_id": { "type": "string", "example": "DD3BB1" }, "category": { "type": "string", "example": "business-contract" }, "fact_level": { "type": "string", "example": "fact" }, "document_record_index": { "type": "integer", "description": "Index of the body record where the role matched.", "example": 6 }, "match_type": { "type": "string", "example": "TEMPLATE" }, "event_sentiment": { "type": "number", "format": "float", "example": 0.49 }, "event_risk": { "type": "number", "format": "float", "example": 0.24 }, "sustainability_sentiment": { "type": "number", "format": "float", "example": 0.24 }, "credit_sentiment": { "type": "number", "format": "float", "example": 0.25 }, "interest_rate_sentiment": { "type": "number", "format": "float", "example": 0 }, "event_detection_distance": { "type": "integer", "example": 0 }, "event_text": { "type": "string", "description": "Supporting snippet for the detected event.", "example": "Example Sensor Corp.: we entered into new contracts" }, "rp_event_detected_entity_id": { "type": "string", "example": "DD3BB1" }, "event_detected_entity_name": { "type": "string", "example": "Example Sensor Corp." } } }, "FetchDocumentAnalyticsEvent": { "type": "object", "description": "Detected narrative or business event with scored roles.", "properties": { "event_similarity_key": { "type": "string", "example": "E7913FBE641945AC0670EEF684B6D8E0" }, "topic": { "type": "string", "example": "business" }, "group": { "type": "string", "example": "products-services" }, "type": { "type": "string", "example": "business-contract" }, "event_relevance": { "type": "integer", "example": 77 }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/FetchDocumentAnalyticsEventRole" } } } }, "FetchDocumentAnalyticsEntity": { "type": "object", "description": "Entity-level analytics aggregated across the document.", "properties": { "rp_entity_id": { "type": "string", "example": "4A6F00" }, "entity_type": { "type": "string", "example": "COMP" }, "entity_name": { "type": "string", "example": "Example Listed Corp." }, "country_code": { "type": "string", "example": "US" }, "document_record_index": { "type": "integer", "example": 217 }, "entity_hierarchy_level": { "type": "integer", "example": 1 }, "entity_detection_type": { "type": "string", "example": "direct" }, "entity_detection_distance": { "type": "integer", "example": 0 }, "entity_relevance": { "type": "integer", "example": 26 }, "entity_sentiment": { "type": "number", "format": "float", "example": 0.25 }, "entity_sentiment_confidence": { "type": "number", "format": "float", "example": 0.05 }, "entity_text_sentiment": { "type": "number", "format": "float", "example": 0.25 }, "entity_text_sent_confidence": { "type": "number", "format": "float", "example": 0.05 }, "analyst_ratings_sentiment": { "type": "integer", "example": 0 }, "multi_stock_sentiment": { "type": "integer", "example": 0 } } }, "FetchDocumentAnalytics": { "type": "object", "description": "Structured analytics returned when downloading annotated RPJSON from the signed URL.", "properties": { "document": { "$ref": "#/components/schemas/FetchDocumentAnalyticsDocument" }, "events": { "type": "array", "description": "Detected events with scored roles.", "items": { "$ref": "#/components/schemas/FetchDocumentAnalyticsEvent" } }, "entities": { "type": "array", "description": "Detected entities with document-level relevance and sentiment.", "items": { "$ref": "#/components/schemas/FetchDocumentAnalyticsEntity" } } } }, "SoftwareVersions": { "type": "object", "description": "Optional pipeline build stamps included with some document payloads.", "properties": { "collection_build": { "type": "string", "example": "0" }, "classification_build": { "type": "string", "example": "707" }, "metadata_build": { "type": "string", "example": "20260513" } } }, "ContentTitleBlock": { "type": "object", "description": "A title content block representing the title of the document.", "properties": { "text": { "type": "string", "description": "Extracted document title", "example": "Tesla Inc: Q1 2025 Earnings Call" }, "sentences": { "type": "array", "description": "Index ranges for title text segments", "items": { "$ref": "#/components/schemas/Sentence" } }, "entities": { "type": "array", "description": "Entities detected inside the title text", "items": { "$ref": "#/components/schemas/TextEntity" } }, "events": { "type": "array", "description": "Optional title-span events with character offsets into the title text.", "items": { "$ref": "#/components/schemas/ContentTitleInlineEvent" } } } }, "ContentTitleInlineEvent": { "type": "object", "description": "Event span anchored on the title text using character indices.", "properties": { "event_similarity_key": { "type": "string", "example": "A1795745A27ECCF46AC3FA2708032A95" }, "start": { "type": "integer", "description": "Start character index in the title text.", "example": 0 }, "end": { "type": "integer", "description": "End character index in the title text.", "example": 54 } } }, "ContentBodyBlock": { "type": "array", "description": "Array of content blocks extracted from the document. Each item represents a block of content such as text paragraphs, tables, or lists. All block types include the common fields defined in ContentBlockCommonFields.", "items": { "oneOf": [ { "$ref": "#/components/schemas/TextBlock" }, { "$ref": "#/components/schemas/TableBlock" }, { "$ref": "#/components/schemas/ListBlock" }, { "$ref": "#/components/schemas/HeadingBlock" }, { "$ref": "#/components/schemas/FooterBlock" } ] } }, "Sentence": { "type": "object", "description": "Sentence segmentation information with sentiment analysis.", "properties": { "start": { "type": "integer", "description": "Start character index of the sentence.", "example": 0 }, "end": { "type": "integer", "description": "End character index of the sentence.", "example": 46 }, "sentiment": { "type": "string", "description": "Sentiment score ranging from -1.00 (negative) to 1.00 (positive).", "example": "0.01" }, "sentiment_confidence": { "type": "string", "description": "Confidence score for the sentiment analysis (0.00 to 1.00).", "example": "0.94" } }, "required": ["start", "end"] }, "TextEntity": { "type": "object", "description": "An entity detected within the text.", "properties": { "rp_entity_id": { "type": "string", "description": "Bigdata.com unique entity identifier.", "example": "DD3BB1" }, "name": { "type": "string", "description": "Display name of the entity.", "example": "Tesla Inc" }, "type": { "type": "string", "description": "Entity type classification.", "enum": ["COMPANY", "PERSON", "PLACE", "PRODUCT", "ORGANIZATION", "ETF"] }, "start": { "type": "integer", "description": "Start character index where the entity appears in the text.", "example": 0 }, "end": { "type": "integer", "description": "End character index where the entity appears in the text.", "example": 9 } }, "required": ["rp_entity_id", "start", "end"] }, "ExternalWebChunkLight": { "type": "object", "description": "Text chunk from an external search result.", "properties": { "cnum": { "type": "integer", "description": "Chunk index within the external result (1-based ordering).", "example": 1 }, "text": { "type": "string", "description": "Chunk text content." } }, "required": [ "cnum", "text" ] }, "ExternalWebChunkStandard": { "type": "object", "description": "Text chunk from an external search result with relevance analytics.", "properties": { "cnum": { "type": "integer", "description": "Chunk index within the external result (1-based ordering).", "example": 1 }, "text": { "type": "string", "description": "Chunk text content." }, "relevance": { "type": "number", "format": "float", "description": "Relevance score between 0 and 1.", "example": 0.85 }, "rerank_relevance": { "type": "number", "format": "float", "description": "Score after reranking, if applicable." } }, "required": [ "cnum", "text" ] }, "ExternalWebSource": { "type": "object", "description": "External source details.", "properties": { "name": { "type": "string", "description": "External source name." } }, "required": [ "name" ] }, "ExternalWebSourceExtended": { "type": "object", "description": "External source details.", "properties": { "name": { "type": "string", "description": "External source name." }, "tier": { "type": "string", "description": "Content tier for organizations billed by token consumption. When present, the default is `content-web`.", "example": "content-web" } }, "required": [ "name" ] }, "ExternalWebResultLight": { "type": "object", "description": "External search result with identity and text.", "properties": { "headline": { "type": "string", "description": "Title of the external page or snippet." }, "timestamp": { "type": "string", "format": "date-time", "description": "Publication or retrieval-related timestamp when available." }, "src_name": { "type": "string", "deprecated": true, "description": "Deprecated display name of the external source. Use `source.name` instead." }, "url": { "type": "string", "format": "uri", "description": "URL of the external result, when available." }, "source": { "$ref": "#/components/schemas/ExternalWebSource" }, "chunks": { "type": "array", "description": "Text chunks for this external result.", "items": { "$ref": "#/components/schemas/ExternalWebChunkLight" } } }, "required": [ "headline", "chunks", "src_name", "source" ] }, "ExternalWebResultStandard": { "type": "object", "description": "External search result with relevance analytics.", "properties": { "headline": { "type": "string", "description": "Title of the external page or snippet." }, "timestamp": { "type": "string", "format": "date-time", "description": "Publication or retrieval-related timestamp when available." }, "src_name": { "type": "string", "deprecated": true, "description": "Deprecated display name of the external source. Use `source.name` instead." }, "url": { "type": "string", "format": "uri", "description": "URL of the external result, when available." }, "source": { "$ref": "#/components/schemas/ExternalWebSource" }, "chunks": { "type": "array", "description": "Text chunks for this external result.", "items": { "$ref": "#/components/schemas/ExternalWebChunkStandard" } } }, "required": [ "headline", "chunks", "src_name", "source" ] }, "ExternalWebResultExtended": { "type": "object", "description": "External search result with relevance analytics and token-based source entitlement information when available.", "properties": { "headline": { "type": "string", "description": "Title of the external page or snippet." }, "timestamp": { "type": "string", "format": "date-time", "description": "Publication or retrieval-related timestamp when available." }, "src_name": { "type": "string", "deprecated": true, "description": "Deprecated display name of the external source. Use `source.name` instead." }, "url": { "type": "string", "format": "uri", "description": "URL of the external result, when available." }, "source": { "$ref": "#/components/schemas/ExternalWebSourceExtended" }, "chunks": { "type": "array", "description": "Text chunks for this external result.", "items": { "$ref": "#/components/schemas/ExternalWebChunkStandard" } } }, "required": [ "headline", "chunks", "src_name", "source" ] }, "SearchSourceLight": { "type": "object", "description": "Details about the source that published the document.", "properties": { "id": { "type": "string", "description": "RavenPack internal ID in the Knowledge Graph.", "example": "D4B903" }, "name": { "type": "string", "description": "Source name.", "example": "Factset Transcripts" } }, "required": [ "id", "name" ] }, "SearchSourceStandard": { "type": "object", "description": "Details about the source that published the document.", "properties": { "id": { "type": "string", "description": "RavenPack internal ID in the Knowledge Graph.", "example": "D4B903" }, "name": { "type": "string", "description": "Source name.", "example": "Factset Transcripts" }, "rank": { "type": "string", "description": "Source ranking. Check Find Sources for more details.", "example": "RANK_1" } }, "required": [ "id", "name" ] }, "SearchSourceExtended": { "type": "object", "description": "Details about the source that published the document.", "properties": { "id": { "type": "string", "description": "RavenPack internal ID in the Knowledge Graph.", "example": "D4B903" }, "name": { "type": "string", "description": "Source name.", "example": "Factset Transcripts" }, "rank": { "type": "string", "description": "Source ranking. Check Find Sources for more details.", "example": "RANK_1" }, "tier": { "type": "string", "description": "Content tier for organizations billed by token consumption. Organizations billed in query units receive `packages` instead." }, "packages": { "type": "array", "description": "Content packages for organizations billed in query units. Organizations billed by token consumption receive `tier` instead.", "items": { "type": "string" }, "example": [ "all", "news" ] } }, "required": [ "id", "name" ], "oneOf": [ { "title": "Tokens", "required": [ "tier" ] }, { "title": "Units", "required": [ "packages" ] } ] }, "SearchChunkBoundingBox": { "type": "object", "description": "PDF bounding box for a chunk.", "properties": { "page": { "type": "integer", "description": "Page number.", "example": 1 }, "bottom": { "type": "number", "format": "float", "description": "Bottom edge of the bounding box." }, "left": { "type": "number", "format": "float", "description": "Left edge of the bounding box." }, "right": { "type": "number", "format": "float", "description": "Right edge of the bounding box." }, "top": { "type": "number", "format": "float", "description": "Top edge of the bounding box." } }, "required": [ "page", "bottom", "left", "right", "top" ] }, "SearchChunkLight": { "type": "object", "description": "Chunk identity and text.", "properties": { "cnum": { "type": "integer", "description": "The index of the chunk in the document. You can use it to sort them in order. The first document chunk has cnum with the value 1.", "example": 7 }, "text": { "type": "string", "description": "The text of the chunk.", "example": "Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below.\nMSFT Price Action: Microsoft stock is up 5.5% to $417.17 year-over-year in after-hours trading Wednesday versus a 52-week trading range of $344.79 to $468.35." } }, "required": [ "cnum", "text" ] }, "SearchChunkStandard": { "type": "object", "description": "Chunk text with search analytics.", "properties": { "cnum": { "type": "integer", "description": "The index of the chunk in the document. You can use it to sort them in order. The first document chunk has cnum with the value 1.", "example": 7 }, "text": { "type": "string", "description": "The text of the chunk.", "example": "Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below.\nMSFT Price Action: Microsoft stock is up 5.5% to $417.17 year-over-year in after-hours trading Wednesday versus a 52-week trading range of $344.79 to $468.35." }, "relevance": { "type": "number", "format": "float", "description": "A score between 0 and 1 indicating how closely the chunk matches the query. Scores are meaningful only within the same search execution.", "example": 0.8949412447701082 }, "sentiment": { "type": "number", "format": "float", "description": "Sentiment score from -1.00 to 1.00 indicating the chunk's expected positive or negative market impact.", "example": 0.33 }, "detections": { "type": "array", "description": "Entities and topics detected in the chunk text.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the detected entity.", "example": "ACE54B" }, "start": { "type": "integer", "description": "Start position of the entity in the chunk text.", "example": 23 }, "end": { "type": "integer", "description": "End position of the entity in the chunk text.", "example": 38 }, "type": { "type": "string", "enum": [ "entity", "topic" ], "description": "Type of the detected entity.", "example": "entity" } }, "required": [ "id", "start", "end", "type" ] } } }, "required": [ "cnum", "text", "relevance" ] }, "SearchChunkExtended": { "type": "object", "description": "Chunk text with search analytics, structured locations, sections, and speakers.", "properties": { "cnum": { "type": "integer", "description": "The index of the chunk in the document. You can use it to sort them in order. The first document chunk has cnum with the value 1.", "example": 7 }, "text": { "type": "string", "description": "The text of the chunk.", "example": "Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below.\nMSFT Price Action: Microsoft stock is up 5.5% to $417.17 year-over-year in after-hours trading Wednesday versus a 52-week trading range of $344.79 to $468.35." }, "relevance": { "type": "number", "format": "float", "description": "A score between 0 and 1 indicating how closely the chunk matches the query. Scores are meaningful only within the same search execution.", "example": 0.8949412447701082 }, "sentiment": { "type": "number", "format": "float", "description": "Sentiment score from -1.00 to 1.00 indicating the chunk's expected positive or negative market impact.", "example": 0.33 }, "detections": { "type": "array", "description": "Entities and topics detected in the chunk text.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the detected entity.", "example": "ACE54B" }, "start": { "type": "integer", "description": "Start position of the entity in the chunk text.", "example": 23 }, "end": { "type": "integer", "description": "End position of the entity in the chunk text.", "example": 38 }, "type": { "type": "string", "enum": [ "entity", "topic" ], "description": "Type of the detected entity.", "example": "entity" } }, "required": [ "id", "start", "end", "type" ] } }, "locations": { "type": "object", "description": "Text coordinates and PDF bounding boxes for the chunk.", "properties": { "text": { "type": "array", "items": { "type": "object", "properties": { "paragraph": { "type": "integer" }, "sentence": { "type": "integer" } }, "required": [ "paragraph", "sentence" ] } }, "boxes": { "type": "array", "items": { "$ref": "#/components/schemas/SearchChunkBoundingBox" } } } }, "sections": { "type": "array", "description": "Document sections containing the chunk, when section metadata is available.", "items": { "type": "string" }, "example": [ "transcript_segment" ] }, "speakers": { "type": "array", "description": "Speakers associated with the chunk, principally for transcripts.", "items": { "type": "object", "properties": { "person": { "type": "string", "description": "Identifier of the speaking person.", "example": "0A1B2C" }, "company": { "type": "string", "description": "Identifier of the company the speaker represents.", "example": "D4B903" }, "position": { "type": "string", "description": "Identifier of the speaker's position.", "example": "P12345" } } } } }, "required": [ "cnum", "text", "relevance" ] }, "SearchDocumentLight": { "type": "object", "description": "Document identity, source identity, URL, and chunk text.", "properties": { "id": { "type": "string", "description": "Unique document identifier, a 32-character hexadecimal string.", "example": "57BB2AD919...." }, "headline": { "type": "string", "description": "Document title.", "example": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call" }, "timestamp": { "type": "string", "format": "date-time", "description": "Document timestamp in ISO 8601 format and UTC.", "example": "2025-04-30T21:30:00Z" }, "source": { "$ref": "#/components/schemas/SearchSourceLight" }, "url": { "type": "string", "description": "URL of the document.", "example": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack" }, "chunks": { "type": "array", "description": "Text chunks from the document.", "items": { "$ref": "#/components/schemas/SearchChunkLight" } } }, "required": [ "id", "headline", "timestamp", "source", "chunks" ] }, "SearchDocumentStandard": { "type": "object", "description": "Document identity, type, source ranking, and chunk analytics.", "properties": { "id": { "type": "string", "description": "Unique document identifier, a 32-character hexadecimal string.", "example": "57BB2AD919...." }, "headline": { "type": "string", "description": "Document title.", "example": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call" }, "timestamp": { "type": "string", "format": "date-time", "description": "Document timestamp in ISO 8601 format and UTC.", "example": "2025-04-30T21:30:00Z" }, "source": { "$ref": "#/components/schemas/SearchSourceStandard" }, "url": { "type": "string", "description": "URL of the document.", "example": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack" }, "chunks": { "type": "array", "description": "Text chunks from the document.", "items": { "$ref": "#/components/schemas/SearchChunkStandard" } }, "document_type": { "type": "string", "description": "High-level content classification.", "example": "INVESTMENT-RESEARCH" } }, "required": [ "id", "headline", "timestamp", "source", "chunks" ] }, "SearchDocumentExtended": { "type": "object", "description": "Document identity, source entitlement information, full indexed metadata, and extended chunk analytics.", "properties": { "id": { "type": "string", "description": "Unique document identifier, a 32-character hexadecimal string.", "example": "57BB2AD919...." }, "headline": { "type": "string", "description": "Document title.", "example": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call" }, "timestamp": { "type": "string", "format": "date-time", "description": "Document timestamp in ISO 8601 format and UTC.", "example": "2025-04-30T21:30:00Z" }, "source": { "$ref": "#/components/schemas/SearchSourceExtended" }, "url": { "type": "string", "description": "URL of the document.", "example": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack" }, "chunks": { "type": "array", "description": "Text chunks from the document.", "items": { "$ref": "#/components/schemas/SearchChunkExtended" } }, "document_type": { "type": "string", "description": "High-level content classification.", "example": "INVESTMENT-RESEARCH" }, "publication_timestamp": { "type": "string", "format": "date-time", "description": "Original publication time in ISO 8601 format. Returned when it differs from the document's primary `timestamp`.", "example": "2025-04-30T21:30:00Z" }, "document_subtype": { "type": "string", "description": "More specific content classification.", "example": "MARKET-UPDATE" }, "original_language": { "type": "string", "description": "ISO language code for the language in which the document was originally published.", "example": "en" }, "tags": { "type": "array", "description": "Source-provided labels used to categorize the document.", "items": { "type": "string" }, "example": [ "earnings", "guidance" ] }, "reporting_period": { "type": "array", "description": "Fiscal reporting periods covered by the document, using values such as `2025Q1`.", "items": { "type": "string" }, "example": [ "2025Q1" ] }, "reporting_entity": { "type": "array", "description": "Knowledge Graph entity IDs for the entities the document reports on.", "items": { "type": "string" }, "example": [ "D4B903" ] }, "title_detections": { "type": "array", "description": "Knowledge Graph entity IDs detected in the document title. Unlike chunk `detections`, these do not include text offsets or detection types.", "items": { "type": "string" }, "example": [ "D4B903", "0A1B2C" ] }, "authors": { "type": "array", "description": "Authors identified for the document.", "items": { "type": "object", "properties": { "person": { "type": "string", "description": "Knowledge Graph ID of the author.", "example": "0A1B2C" }, "company": { "type": "string", "description": "Knowledge Graph ID of the author's affiliated company, when available.", "example": "D4B903" } } } } }, "required": [ "id", "headline", "timestamp", "source", "chunks" ] }, "SearchResponseMetadata": { "type": "object", "description": "Request metadata and timing information.", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request.", "example": "user_2k3Z4SerTUIieyCfQhGR5UF2Af3" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the response was generated.", "example": "2025-09-12T11:10:46.019077+00:00" }, "audit": { "type": "object", "description": "Detailed breakdown of the resolved queries that were executed. Only present in Smart mode when `include_audit` is set to `true` in the request.", "properties": { "queries": { "type": "array", "description": "Array of resolved queries that were executed by the system.", "items": {} } }, "required": [ "queries" ] }, "total_response_tokens": { "type": "integer", "minimum": 0, "description": "Total number of tokens in the response." } }, "required": [ "timestamp" ] }, "SearchResponseError": { "type": "object", "description": "Error reported while processing part of the search response.", "properties": { "message": { "type": "string", "description": "Error message." } } }, "SearchPagination": { "type": "object", "description": "Pagination state for the search response.", "properties": { "cursor": { "type": "string", "description": "Cursor for the next page, when available." }, "has_cursor": { "type": "boolean", "description": "Whether another page is available." } }, "required": [ "has_cursor" ] }, "SearchResponseLight": { "title": "Light", "type": "object", "description": "Search response containing document identity and chunk text.", "properties": { "results": { "type": "array", "description": "Documents and chunks that match the query criteria.", "items": { "$ref": "#/components/schemas/SearchDocumentLight" } }, "external_results": { "type": "object", "description": "External search results grouped by source, such as `web`.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalWebResultLight" } } }, "metadata": { "$ref": "#/components/schemas/SearchResponseMetadata" }, "errors": { "type": "array", "description": "Errors reported while processing the search response.", "items": { "$ref": "#/components/schemas/SearchResponseError" } }, "pagination": { "$ref": "#/components/schemas/SearchPagination" }, "usage": { "$ref": "#/components/schemas/SearchUsage" } }, "required": [ "results", "external_results", "usage" ] }, "SearchResponseStandard": { "title": "Standard", "type": "object", "description": "Search response containing source ranking and chunk analytics.", "properties": { "results": { "type": "array", "description": "Documents and chunks that match the query criteria.", "items": { "$ref": "#/components/schemas/SearchDocumentStandard" } }, "external_results": { "type": "object", "description": "External search results grouped by source, such as `web`.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalWebResultStandard" } } }, "metadata": { "$ref": "#/components/schemas/SearchResponseMetadata" }, "errors": { "type": "array", "description": "Errors reported while processing the search response.", "items": { "$ref": "#/components/schemas/SearchResponseError" } }, "pagination": { "$ref": "#/components/schemas/SearchPagination" }, "usage": { "$ref": "#/components/schemas/SearchUsage" } }, "required": [ "results", "external_results", "usage" ] }, "SearchResponseExtended": { "title": "Extended", "type": "object", "description": "Search response containing source entitlement information, full indexed metadata, and extended chunk analytics.", "properties": { "results": { "type": "array", "description": "Documents and chunks that match the query criteria.", "items": { "$ref": "#/components/schemas/SearchDocumentExtended" } }, "external_results": { "type": "object", "description": "External search results grouped by source, such as `web`.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalWebResultExtended" } } }, "metadata": { "$ref": "#/components/schemas/SearchResponseMetadata" }, "errors": { "type": "array", "description": "Errors reported while processing the search response.", "items": { "$ref": "#/components/schemas/SearchResponseError" } }, "pagination": { "$ref": "#/components/schemas/SearchPagination" }, "usage": { "$ref": "#/components/schemas/SearchUsage" } }, "required": [ "results", "external_results", "usage" ] }, "NormalizedCoordinates": { "type": "object", "description": "Bounding box coordinates normalized to page dimensions (values between 0 and 1).", "properties": { "page": { "type": "integer", "description": "Page number (1-indexed).", "example": 1 }, "x": { "type": "number", "format": "float", "description": "X coordinate (left edge) normalized to page width.", "example": 0.1 }, "y": { "type": "number", "format": "float", "description": "Y coordinate (top edge) normalized to page height.", "example": 0.15 }, "width": { "type": "number", "format": "float", "description": "Width normalized to page width.", "example": 0.8 }, "height": { "type": "number", "format": "float", "description": "Height normalized to page height.", "example": 0.05 } } }, "ContentBlockCommonFields": { "type": "object", "description": "Common fields present in all content block types (TextBlock, TableBlock, ListBlock). These fields may appear alongside the block-specific fields.", "properties": { "normalized_coordinates": { "type": "array", "description": "Bounding boxes normalized to page dimensions", "items": { "$ref": "#/components/schemas/NormalizedCoordinates" } }, "text": { "type": "string", "description": "Extracted visible text (if any)", "example": "The first quarter results were announced today." }, "sentences": { "type": "array", "description": "Index ranges for sentence segmentation", "items": { "$ref": "#/components/schemas/Sentence" } }, "entities": { "type": "array", "description": "Entities detected in the text", "items": { "$ref": "#/components/schemas/TextEntity" } } } }, "TextBlock": { "title": "Paragraph", "type": "object", "description": "A text content block representing paragraphs, headings, or other text elements. Includes all fields from ContentBlockCommonFields.", "allOf": [ { "$ref": "#/components/schemas/ContentBlockCommonFields" } ] }, "TableBlock": { "title": "Table", "type": "object", "description": "A table content block. Includes all fields from ContentBlockCommonFields.", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Table block type.", "enum": ["TABLE"] }, "rows": { "type": "array", "description": "Row definitions for the table.", "items": { "$ref": "#/components/schemas/TableRow" } } }, "required": ["type","rows"] }, { "$ref": "#/components/schemas/ContentBlockCommonFields" } ] }, "HeadingBlock": { "title": "Heading", "type": "object", "description": "A heading content block. Includes all fields from ContentBlockCommonFields.", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Heading block type.", "enum": ["HEADING"] } }, "required": ["type"] }, { "$ref": "#/components/schemas/ContentBlockCommonFields" } ] }, "FooterBlock": { "title": "Footer", "type": "object", "description": "A footer content block. Includes all fields from ContentBlockCommonFields.", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "Footer block type.", "enum": ["FOOTER"] } }, "required": ["type"] }, { "$ref": "#/components/schemas/ContentBlockCommonFields" } ] }, "TableRow": { "type": "object", "description": "A row within a table.", "properties": { "cells": { "type": "array", "description": "Cells in the row.", "items": { "$ref": "#/components/schemas/TableCell" } } }, "required": ["cells"] }, "TableCell": { "type": "object", "description": "A cell within a table row.", "properties": { "content": { "type": "array", "description": "Content objects within the cell.", "items": { "$ref": "#/components/schemas/CellContent" } } }, "required": ["type", "content"] }, "CellContent": { "type": "object", "description": "Simple text content within a table cell or list entry.", "properties": { "text": { "type": "string", "description": "Text content.", "example": "Quarter" } }, "required": ["text"] }, "ListBlock": { "title": "List", "type": "object", "description": "A list content block (ordered or unordered). Includes all fields from ContentBlockCommonFields.", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "List block type.", "enum": ["LIST_ORDERED", "LIST_UNORDERED"] }, "entries": { "type": "array", "description": "List entries/items.", "items": { "$ref": "#/components/schemas/ListEntry" } } }, "required": ["type","entries"] }, { "$ref": "#/components/schemas/ContentBlockCommonFields" } ] }, "ListEntry": { "type": "object", "description": "An entry within a list.", "properties": { "key": { "type": "string", "description": "Bullet character for unordered lists (e.g., '•') or list number for ordered lists (e.g., '1').", "example": "•" }, "content": { "type": "array", "description": "Content objects within the list entry.", "items": { "$ref": "#/components/schemas/CellContent" } } }, "required": ["key", "content"] }, "QuotaUsageUnits": { "title": "Units", "type": "object", "description": "Usage under the query-units consumption model.", "properties": { "api_query_units": { "type": "number", "format": "float", "description": "Number of API query units consumed by this request.", "example": 0.7 } }, "required": ["api_query_units"] }, "QuotaUsageTokenCount": { "title": "Tokens", "type": "object", "description": "Token usage for the request.", "properties": { "tokens": { "type": "integer", "description": "Total number of tokens consumed by this request.", "example": 17 } }, "required": ["tokens"] }, "QuotaUsageTokens": { "title": "Tokens", "type": "object", "description": "Token usage for the request, keyed by content tier. Each key ends in `_tokens`.", "not": { "required": [ "api_query_units" ] }, "additionalProperties": { "type": "integer" }, "example": { "premium_news_tokens": 300, "regulatory_filings_tokens": 500 } }, "SearchUsage": { "type": "object", "description": "Usage consumed by the request.", "oneOf": [ { "$ref": "#/components/schemas/QuotaUsageUnits" }, { "$ref": "#/components/schemas/QuotaUsageTokens" } ] }, "AggregateSearchUsage": { "type": "object", "description": "Usage consumed by the request.", "oneOf": [ { "$ref": "#/components/schemas/QuotaUsageUnits" }, { "$ref": "#/components/schemas/QuotaUsageTokenCount" } ] } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/v1/search": { "post": { "tags": ["Search"], "summary": "Search documents", "operationId": "search_documents", "description": "Easily find the most relevant information from trusted sources and your own data. Use it to power agents that give accurate, real-time answers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search_mode": { "type": "string", "description": "**fast** (default): Runs a single query using the specified filters. Best for pre-processed queries where you control the filters.\n\n**smart**: Analyzes the query text to automatically define search filters and runs multiple sub-queries to ensure better coverage. Ideal for sending user questions directly without pre-processing. When using smart mode, only `timestamp` and `source` filters are allowed; using any other filters will result in a 400 Bad Request error. \n\nClick [here for a more detailed comparison](/getting-started/bigdata_api_pricing#what-is-the-difference-between-fast-and-smart-search-modes)", "enum": ["fast", "smart"] }, "include_audit": { "type": "boolean", "default": false, "description": "**Smart mode only.** When set to `true`, the response metadata includes an `audit` object listing the sub-queries that Smart mode actually ran, with their resolved filters and ranking settings. Useful for debugging and understanding how Smart mode interpreted your request." }, "response_detail": { "type": "string", "enum": ["light", "standard", "extended"], "default": "standard", "description": "Controls how much detail is returned for each result." }, "query": { "type": "object", "description": "In Fast mode, provide at least one of `text`, `texts` or `filters`. In smart mode, only `text` is required.", "properties": { "text": { "type": "string", "description": "Natural-language search string. Optional in Fast mode when `texts` or `filters` are provided, required in smart mode. Mutually exclusive with `texts`." }, "texts": { "type": "array", "description": "Multiple natural-language search strings (max 5). Use when a single query cannot capture all aspects of your intent. Mutually exclusive with `text`. When the reranker is enabled and more than one text is provided, you must also provide `ranking_params.reranker.text`.", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "example": ["supply chain disruptions", "logistics delays", "shipping bottlenecks"] }, "context": { "type": "string", "description": "**Smart mode only.** Optional natural-language hints that help Smart mode narrow or disambiguate results, such as content preferences (e.g.,`search in my private files`, `Financial Times content`, `broker research from JPMorgan`). Keep the actual question in `text` and use context only for additional hints. Entities detected in the context are not used for entity hinting; time periods in the context are.", "example": "search in my private files" }, "filters": { "type": "object", "properties": { "timestamp": { "type": "object", "description": "Temporal filter to retrieve documents with a timestamp within a start and end date.", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')" }, "end": { "type": "string", "format": "date-time", "description": "End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')" } } }, "document_type": { "type": "object", "description": "Document type filter to retrieve documents of specific types. Values can be either plain strings (deprecated) or objects with 'type' and optional 'subtypes' for more precise filtering.", "properties": { "mode": { "type": "string", "description": "Filter mode for document type selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document type values to include or exclude based on the mode. Each value can be a string (deprecated) or an object with 'type' and optional 'subtypes'.", "items": { "oneOf": [ { "type": "object", "description": "Document type object with type and optional subtypes for more precise filtering.", "properties": { "type": { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "description": "The document type." }, "subtypes": { "type": "array", "description": "Optional array of subtypes for more specific filtering. Supported subtypes vary by type:\nFor [FILING](/getting-started/search/query_filters#filing): SEC_10_K, SEC_10_Q, SEC_8_K, SEC_20_F, SEC_S_1, SEC_S_3, SEC_6_K, SEC_424B2, SEC_DEF_14A, SEC_485APOS, SEC_485BPOS, SEC_497, SEC_497AD, SEC_497J, SEC_497K, SEC_497VPI, SEC_497VPSUB, SEC_497VPU, SEC_N_CSR, SEC_N_CSR_A, SEC_N_CSRS, SEC_N_CSRS_A, SEC_NPORT_P_A, SEC_NT_NCSR, SEC_NT_NCSR_A, SEC_NT_NPORT_P, SEC_NTFNCSR.\n\nFor [TRANSCRIPT and TRANSCRIPT-PRESENTATION](/getting-started/search/query_filters#transcript): ANALYST_INVESTOR_SHAREHOLDER_MEETING, CONFERENCE_CALL, GENERAL_PRESENTATION, EARNINGS_CALL, EARNINGS_RELEASE, GUIDANCE_CALL, SALES_REVENUE_CALL, SALES_REVENUE_RELEASE, SPECIAL_SITUATION_MA, SHAREHOLDERS_MEETING, MANAGEMENT_PLAN_ANNOUNCEMENT, INVESTOR_CONFERENCE_CALL.\n\nFor [INVESTMENT-RESEARCH](/getting-started/search/query_filters#investment-research): COMPANY_REPORT, COVERAGE_ANALYSIS, ECONOMIC_REPORT, FIXED_INCOME_REPORT, FUND_REPORT, FX_AND_DERIVATIVES_REPORT, GENERIC_REPORT, INDEX_REPORT, INDUSTRY_REPORT, MARKET_UPDATE, PORTFOLIO_STRATEGY, PORTFOLIO_SUMMARY, RATING_REPORT, RESEARCH_NOTE, THEMATIC_ANALYSIS.", "items": { "type": "string", "enum": [ "SEC_10_K", "SEC_10_Q", "SEC_8_K", "SEC_20_F", "SEC_S_1", "SEC_S_3", "SEC_6_K", "SEC_424B2", "SEC_DEF_14A", "SEC_485APOS", "SEC_485BPOS", "SEC_497", "SEC_497AD", "SEC_497J", "SEC_497K", "SEC_497VPI", "SEC_497VPSUB", "SEC_497VPU", "SEC_N_CSR", "SEC_N_CSR_A", "SEC_N_CSRS", "SEC_N_CSRS_A", "SEC_NPORT_P_A", "SEC_NT_NCSR", "SEC_NT_NCSR_A", "SEC_NT_NPORT_P", "SEC_NTFNCSR", "ANALYST_INVESTOR_SHAREHOLDER_MEETING", "CONFERENCE_CALL", "GENERAL_PRESENTATION", "EARNINGS_CALL", "EARNINGS_RELEASE", "GUIDANCE_CALL", "SALES_REVENUE_CALL", "SALES_REVENUE_RELEASE", "SPECIAL_SITUATION_MA", "SHAREHOLDERS_MEETING", "MANAGEMENT_PLAN_ANNOUNCEMENT", "INVESTOR_CONFERENCE_CALL", "COMPANY_REPORT", "COVERAGE_ANALYSIS", "ECONOMIC_REPORT", "FIXED_INCOME_REPORT", "FUND_REPORT", "FX_AND_DERIVATIVES_REPORT", "GENERIC_REPORT", "INDEX_REPORT", "INDUSTRY_REPORT", "MARKET_UPDATE", "PORTFOLIO_STRATEGY", "RATING_REPORT", "RESEARCH_NOTE", "THEMATIC_ANALYSIS", "PORTFOLIO_SUMMARY" ] } } }, "required": ["type"] }, { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "deprecated": true, "description": "Deprecated: Use the object format with 'type' and optional 'subtypes' instead." } ] } } }, "required": ["mode", "values"] }, "original_language": { "type": "object", "description": "Original language filter to retrieve documents based on the language in which the content was originally published. Documents remain searchable in English regardless of their original language: this filter selects on the source language, not on the language of the text returned.", "properties": { "mode": { "type": "string", "description": "Filter mode for original language selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of original languages to include or exclude based on the mode. Values are lowercase ISO 639-1 codes, for example `en`, `de` or `ja`, with `zh-Hans` and `zh-Hant` for Simplified and Traditional Chinese. Values are not validated against a fixed list, as new original languages are onboarded over time.", "items": { "type": "string" }, "example": ["de", "ja"] } }, "required": ["mode", "values"] }, "source": { "type": "object", "description": "Source filter to retrieve documents from specific sources.", "properties": { "mode": { "type": "string", "description": "Filter mode for source selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of source IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["ED68DC"] } }, "required": ["mode", "values"] }, "category": { "type": "object", "description": "Category filter to retrieve documents from specific categories. This enables selecting a related set of sources without having to add a long list of source IDs.", "properties": { "mode": { "type": "string", "description": "Filter mode for category selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of categories to include or exclude based on the mode.", "items": { "type": "string", "enum": ["expert_interviews", "filings", "my_files", "news", "news_premium", "news_public", "podcasts", "research", "research_academic_journals", "research_investment_research", "transcripts"] } } }, "required": ["mode", "values"] }, "tier": { "type": "object", "description": "Content tier filter to retrieve documents from specific content tiers. Tiers are how content is packaged and priced under the token-based consumption model.", "properties": { "mode": { "type": "string", "description": "Filter mode for content tier selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of content tiers to include or exclude based on the mode.", "items": { "type": "string", "enum": [ "corporate-communications", "premium-news", "expert-interviews", "earnings-transcripts", "regulatory-filings", "podcasts", "web", "private-data" ] } } }, "required": ["mode", "values"] }, "keyword": { "type": "object", "description": "Keyword filter to retrieve chunks based on keyword presence.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of keywords that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of keywords where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [] }, "none_of": { "type": "array", "description": "Array of keywords that must not be present in the chunk.", "items": { "type": "string" }, "example": ["operating"] } }, "required": ["all_of", "any_of", "none_of"] }, "entity": { "type": "object", "description": "Entity filter to retrieve chunks where entities were identified.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of entity IDs that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of entity IDs where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["228D42"] }, "none_of": { "type": "array", "description": "Array of entity IDs that must not be present in the document.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sentiment": { "type": "object", "description": "Sentiment filter to retrieve chunks based on sentiment score. All chunks contain a sentiment score ranging from -1.00 to 1.00, indicating how that chunk might impact the market and whether it will have a positive or negative effect.", "properties": { "ranges": { "type": "array", "description": "Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.", "items": { "type": "object", "properties": { "min": { "type": "number", "format": "float", "description": "Minimum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -1.0 }, "max": { "type": "number", "format": "float", "description": "Maximum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -0.3 } }, "required": ["min", "max"] }, "example": [ { "min": -1.0, "max": -0.3 }, { "min": 0.3, "max": 1.0 } ] }, "values": { "type": "array", "description": "Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering.", "deprecated": true, "items": { "type": "string", "enum": ["positive", "negative", "neutral"], "description": "Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1)" } } } }, "reporting_entities": { "type": "array", "description": "Select one or multiple companies for which the returned documents must have been reported by.", "items": { "type": "string" }, "example": ["228D42"] }, "reporting_periods": { "type": "array", "description": "Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).", "items": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "description": "Fiscal year", "example": 2024 }, "fiscal_quarter": { "type": "integer", "description": "Fiscal quarter (1-4)", "minimum": 1, "maximum": 4, "example": 3 } }, "required": ["fiscal_year", "fiscal_quarter"] }, "example": [ { "fiscal_year": 2024, "fiscal_quarter": 3 } ] }, "topic": { "type": "object", "description": "Topic filter to retrieve chunks based on topic presence. Example: {\"any_of\": [\"business,stock-prices,stock-price-volatility,down,\"]} to find documents about stock price volatility.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of topics that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of topics where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["business,stock-prices,stock-price-volatility,down,"] }, "none_of": { "type": "array", "description": "Array of topics that must not be present in the chunk.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "authors": { "type": "object", "description": "Filter by document author. Useful for investment research.", "properties": { "type": { "type": "string", "enum": [ "company", "person", "position" ], "description": "`person` for individuals, `company` for firms, or `position` for roles." }, "values": { "type": "array", "description": "Entity IDs to filter by.", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "type", "values" ], "example": { "type": "person", "values": [ "4L0FDS" ] } }, "speakers": { "type": "object", "description": "Filter by speaker. Useful for transcripts and expert interviews.", "properties": { "type": { "type": "string", "enum": [ "company", "person", "position" ], "description": "`person` for individuals, `company` for firms, or `position` for roles." }, "values": { "type": "array", "description": "Entity IDs to filter by.", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "type", "values" ], "example": { "type": "company", "values": [ "DF67D7" ] } }, "sections": { "type": "object", "description": "Section filter to restrict transcript and expert interview results to specific sections.", "properties": { "any_of": { "type": "array", "description": "Array of transcript and expert interview sections where at least one must be present. Values are case-insensitive.", "items": { "type": "string", "enum": [ "MANAGEMENT-DISCUSSION", "QUESTION-ANSWER" ] }, "example": ["QUESTION-ANSWER"] } }, "required": ["any_of"] }, "tag": { "type": "object", "description": "Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.", "properties": { "any_of": { "type": "array", "description": "Array of tags where at least one must be present in the uploaded file.", "items": { "type": "string" }, "example": ["research-report", "any-tag"] } }, "required": ["any_of"] }, "document": { "type": "object", "description": "Document filter to restrict the search to a list of specified documents. Use document IDs (e.g., from a previous search response) to search only within those documents.", "properties": { "mode": { "type": "string", "description": "Filter mode for document selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["3C54E042B2B19B244F57D3C6415439D1"] } }, "required": ["mode", "values"] }, "chunk": { "type": "object", "description": "Chunk filter to narrow the search to a particular section within the document. Use when expanding the context of a previously retrieved chunk (e.g., from the 3rd chunk to the 7th). Useful to expand context around a chunk that was previously retrieved. Chunk indices are 1-based.", "properties": { "from": { "type": "integer", "description": "1-based index of the first chunk to include in the search range.", "example": 3 }, "to": { "type": "integer", "description": "1-based index of the last chunk to include in the search range (inclusive).", "example": 7 } }, "required": ["from", "to"] } } }, "external_search": { "type": "object", "description": "Add external sources (e.g. live web) to your search. Use `INCLUDE` to get both Bigdata.com content and external results, or `ONLY` to search external sources exclusively. Results appear in `external_results` grouped by source. \n\nFor external search, only `query.text` is used; any other query parameters apply only to Bigdata content. \n\nIn Fast mode, external search is always called when enabled. In Smart mode, only `INCLUDE` mode is supported—the system decides whether external search is needed based on query intent. If not called, no additional cost is incurred. \n\n**Note:** Not available in Batch Search.", "properties": { "mode": { "type": "string", "description": "`INCLUDE` returns Bigdata.com content plus external results. `ONLY` returns external results exclusively.", "enum": ["INCLUDE", "ONLY"] }, "values": { "type": "array", "description": "Which external sources to search. Available: `web`. `social` coming soon.", "items": { "type": "string", "enum": ["web"] }, "minItems": 1 } }, "required": ["mode"] }, "ranking_params": { "type": "object", "description": "Groups parameters that affect the ranking algorithm and determine chunk relevance.", "properties": { "content_diversification": { "type": "object", "description": "Prevents single-source bias and semantically redundant content.", "properties": { "enabled": { "type": "boolean", "description": "If set to `true`, results are balanced across a wider range of providers and distinct viewpoints. Default: `true`." } } }, "source_boost": { "type": "number", "format": "float", "description": "Controls how much the source rank influences relevance. Range: 0-10. Default: 1.0. 0 → source rank has no effect. 10 → maximum effect, boosting chunks from premium sources.", "minimum": 0, "maximum": 10, "example": 1.0 }, "freshness_boost": { "type": "number", "format": "float", "description": "Controls the influence of document timestamp on relevance. Range: 0-10. Default: 1.0. 0 → publishing time is ignored (useful for point-in-time research). 10 → most recent documents are heavily prioritized.", "minimum": 0, "maximum": 10, "example": 1.0 }, "reranker": { "type": "object", "description": "Applies a second ranking phase to improve precision. A cross-encoder model re-ranks the top candidates using the input query.", "properties": { "enabled": { "type": "boolean", "description": "Enable the re-ranker. True by default." }, "threshold": { "type": "number", "format": "float", "description": "Reranker threshold to filter results by relevance score. Range: 0.0 to 1.0. The default reranker uses a threshold of 0.2, but you can set a custom threshold to improve precision and reduce noise. Higher values return fewer, more relevant results.", "minimum": 0.0, "maximum": 1.0, "example": 0.8 }, "text": { "type": "string", "description": "Custom text for the cross-encoder to rank against. When using `query.text`, the reranker uses that value by default. When using `query.texts` with more than one item, this field is required if the reranker is enabled — provide a single string that captures your overall intent.", "example": "supply chain impact on manufacturing" } }, "required": ["enabled"] } } }, "max_chunks": { "type": "integer", "description": "Maximum number of chunks to retrieve. It must be lower than or equal to 1000.\nThe response may contain fewer chunks after deduplication and/or reranking filtering. Check the response `usage` object to see the request's actual consumption. See [Monitor usage](/how-to-guides/monitor_usage).", "example": 10 }, "auto_enrich_filters": { "type": "boolean", "description": "Advanced parameter that controls automatic enrichment of filters using the query text. When set to true (default), the system automatically extracts and adds relevant filter values from the query text. Set to false when you have created a strict query with specific keywords and entity filters and you do not want any extra values added to those filters." } } } }, "required": ["search_mode", "query"], "example": { "search_mode": "fast", "query": { "text": "Type a question to retrieve documents chunks" } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "description": "The response schema corresponds to the requested `response_detail` value.", "anyOf": [ { "$ref": "#/components/schemas/SearchResponseLight" }, { "$ref": "#/components/schemas/SearchResponseStandard" }, { "$ref": "#/components/schemas/SearchResponseExtended" } ] } } } } } } }, "/v1/search/volume": { "post": { "tags": ["Search"], "summary": "Search volume", "operationId": "search_volume", "description": "Get document and chunk volume statistics over time for a search query, aggregated by date with sentiment analysis.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "Provide at least one of `text`, `texts` or `filters`.", "properties": { "text": { "type": "string", "description": "Natural-language search string. Optional when `texts` or `filters` are provided. Mutually exclusive with `texts`.", "example": "Tariffs impact" }, "texts": { "type": "array", "description": "Multiple natural-language search strings (max 5). Use when a single query cannot capture all aspects of your intent. Mutually exclusive with `text`.", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "example": ["supply chain disruptions", "logistics delays", "shipping bottlenecks"] }, "filters": { "type": "object", "properties": { "timestamp": { "type": "object", "description": "Temporal filter to retrieve documents with a timestamp within a start and end date. On this endpoint, `start` and `end` can be at most one year apart. Cover longer periods with multiple requests.", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')" }, "end": { "type": "string", "format": "date-time", "description": "End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')" } } }, "document_type": { "type": "object", "description": "Document type filter to retrieve documents of specific types. Values can be either plain strings (deprecated) or objects with 'type' and optional 'subtypes' for more precise filtering.", "properties": { "mode": { "type": "string", "description": "Filter mode for document type selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document type values to include or exclude based on the mode. Each value can be a string (deprecated) or an object with 'type' and optional 'subtypes'.", "items": { "oneOf": [ { "type": "object", "description": "Document type object with type and optional subtypes for more precise filtering.", "properties": { "type": { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "description": "The document type." }, "subtypes": { "type": "array", "description": "Optional array of subtypes for more specific filtering. Supported subtypes vary by type:\nFor [FILING](/getting-started/search/query_filters#filing): SEC_10_K, SEC_10_Q, SEC_8_K, SEC_20_F, SEC_S_1, SEC_S_3, SEC_6_K, SEC_424B2, SEC_DEF_14A, SEC_485APOS, SEC_485BPOS, SEC_497, SEC_497AD, SEC_497J, SEC_497K, SEC_497VPI, SEC_497VPSUB, SEC_497VPU, SEC_N_CSR, SEC_N_CSR_A, SEC_N_CSRS, SEC_N_CSRS_A, SEC_NPORT_P_A, SEC_NT_NCSR, SEC_NT_NCSR_A, SEC_NT_NPORT_P, SEC_NTFNCSR.\n\nFor [TRANSCRIPT and TRANSCRIPT-PRESENTATION](/getting-started/search/query_filters#transcript): ANALYST_INVESTOR_SHAREHOLDER_MEETING, CONFERENCE_CALL, GENERAL_PRESENTATION, EARNINGS_CALL, EARNINGS_RELEASE, GUIDANCE_CALL, SALES_REVENUE_CALL, SALES_REVENUE_RELEASE, SPECIAL_SITUATION_MA, SHAREHOLDERS_MEETING, MANAGEMENT_PLAN_ANNOUNCEMENT, INVESTOR_CONFERENCE_CALL.\n\nFor [INVESTMENT-RESEARCH](/getting-started/search/query_filters#investment-research): COMPANY_REPORT, COVERAGE_ANALYSIS, ECONOMIC_REPORT, FIXED_INCOME_REPORT, FUND_REPORT, FX_AND_DERIVATIVES_REPORT, GENERIC_REPORT, INDEX_REPORT, INDUSTRY_REPORT, MARKET_UPDATE, PORTFOLIO_STRATEGY, PORTFOLIO_SUMMARY, RATING_REPORT, RESEARCH_NOTE, THEMATIC_ANALYSIS.", "items": { "type": "string", "enum": [ "SEC_10_K", "SEC_10_Q", "SEC_8_K", "SEC_20_F", "SEC_S_1", "SEC_S_3", "SEC_6_K", "SEC_424B2", "SEC_DEF_14A", "SEC_485APOS", "SEC_485BPOS", "SEC_497", "SEC_497AD", "SEC_497J", "SEC_497K", "SEC_497VPI", "SEC_497VPSUB", "SEC_497VPU", "SEC_N_CSR", "SEC_N_CSR_A", "SEC_N_CSRS", "SEC_N_CSRS_A", "SEC_NPORT_P_A", "SEC_NT_NCSR", "SEC_NT_NCSR_A", "SEC_NT_NPORT_P", "SEC_NTFNCSR", "ANALYST_INVESTOR_SHAREHOLDER_MEETING", "CONFERENCE_CALL", "GENERAL_PRESENTATION", "EARNINGS_CALL", "EARNINGS_RELEASE", "GUIDANCE_CALL", "SALES_REVENUE_CALL", "SALES_REVENUE_RELEASE", "SPECIAL_SITUATION_MA", "SHAREHOLDERS_MEETING", "MANAGEMENT_PLAN_ANNOUNCEMENT", "INVESTOR_CONFERENCE_CALL", "COMPANY_REPORT", "COVERAGE_ANALYSIS", "ECONOMIC_REPORT", "FIXED_INCOME_REPORT", "FUND_REPORT", "FX_AND_DERIVATIVES_REPORT", "GENERIC_REPORT", "INDEX_REPORT", "INDUSTRY_REPORT", "MARKET_UPDATE", "PORTFOLIO_STRATEGY", "RATING_REPORT", "RESEARCH_NOTE", "THEMATIC_ANALYSIS", "PORTFOLIO_SUMMARY" ] } } }, "required": ["type"] }, { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "deprecated": true, "description": "Deprecated: Use the object format with 'type' and optional 'subtypes' instead." } ] } } }, "required": ["mode", "values"] }, "original_language": { "type": "object", "description": "Original language filter to retrieve documents based on the language in which the content was originally published. Documents remain searchable in English regardless of their original language: this filter selects on the source language, not on the language of the text returned.", "properties": { "mode": { "type": "string", "description": "Filter mode for original language selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of original languages to include or exclude based on the mode. Values are lowercase ISO 639-1 codes, for example `en`, `de` or `ja`, with `zh-Hans` and `zh-Hant` for Simplified and Traditional Chinese. Values are not validated against a fixed list, as new original languages are onboarded over time.", "items": { "type": "string" }, "example": ["de", "ja"] } }, "required": ["mode", "values"] }, "source": { "type": "object", "description": "Source filter to retrieve documents from specific sources.", "properties": { "mode": { "type": "string", "description": "Filter mode for source selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of source IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["ED68DC"] } }, "required": ["mode", "values"] }, "category": { "type": "object", "description": "Category filter to retrieve documents from specific categories. This enables selecting a related set of sources without having to add a long list of source IDs.", "properties": { "mode": { "type": "string", "description": "Filter mode for category selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of categories to include or exclude based on the mode.", "items": { "type": "string", "enum": ["expert_interviews", "filings", "my_files", "news", "news_premium", "news_public", "podcasts", "research", "research_academic_journals", "research_investment_research", "transcripts"] } } }, "required": ["mode", "values"] }, "tier": { "type": "object", "description": "Content tier filter to retrieve documents from specific content tiers. Tiers are how content is packaged and priced under the token-based consumption model.", "properties": { "mode": { "type": "string", "description": "Filter mode for content tier selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of content tiers to include or exclude based on the mode.", "items": { "type": "string", "enum": [ "corporate-communications", "premium-news", "expert-interviews", "earnings-transcripts", "regulatory-filings", "podcasts", "web", "private-data" ] } } }, "required": ["mode", "values"] }, "keyword": { "type": "object", "description": "Keyword filter to retrieve chunks based on keyword presence.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of keywords that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of keywords where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [] }, "none_of": { "type": "array", "description": "Array of keywords that must not be present in the chunk.", "items": { "type": "string" }, "example": ["operating"] } }, "required": ["all_of", "any_of", "none_of"] }, "entity": { "type": "object", "description": "Entity filter to retrieve chunks where entities were identified.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of entity IDs that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of entity IDs where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["228D42"] }, "none_of": { "type": "array", "description": "Array of entity IDs that must not be present in the document.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sentiment": { "type": "object", "description": "Sentiment filter to retrieve chunks based on sentiment score. All chunks contain a sentiment score ranging from -1.00 to 1.00, indicating how that chunk might impact the market and whether it will have a positive or negative effect.", "properties": { "ranges": { "type": "array", "description": "Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.", "items": { "type": "object", "properties": { "min": { "type": "number", "format": "float", "description": "Minimum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -1.0 }, "max": { "type": "number", "format": "float", "description": "Maximum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -0.3 } }, "required": ["min", "max"] }, "example": [ { "min": -1.0, "max": -0.3 }, { "min": 0.3, "max": 1.0 } ] }, "values": { "type": "array", "description": "Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering.", "deprecated": true, "items": { "type": "string", "enum": ["positive", "negative", "neutral"], "description": "Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1)" } } } }, "reporting_entities": { "type": "array", "description": "Select one or multiple companies for which the returned documents must have been reported by.", "items": { "type": "string" }, "example": ["228D42"] }, "reporting_periods": { "type": "array", "description": "Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).", "items": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "description": "Fiscal year", "example": 2024 }, "fiscal_quarter": { "type": "integer", "description": "Fiscal quarter (1-4)", "minimum": 1, "maximum": 4, "example": 3 } }, "required": ["fiscal_year", "fiscal_quarter"] }, "example": [ { "fiscal_year": 2024, "fiscal_quarter": 3 } ] }, "topic": { "type": "object", "description": "Topic filter to retrieve chunks based on topic presence. Example: {\"any_of\": [\"business,stock-prices,stock-price-volatility,down,\"]} to find documents about stock price volatility.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of topics that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of topics where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["business,stock-prices,stock-price-volatility,down,"] }, "none_of": { "type": "array", "description": "Array of topics that must not be present in the chunk.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sections": { "type": "object", "description": "Section filter to restrict transcript and expert interview results to specific sections.", "properties": { "any_of": { "type": "array", "description": "Array of transcript and expert interview sections where at least one must be present. Values are case-insensitive.", "items": { "type": "string", "enum": [ "MANAGEMENT-DISCUSSION", "QUESTION-ANSWER" ] }, "example": ["QUESTION-ANSWER"] } }, "required": ["any_of"] }, "tag": { "type": "object", "description": "Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.", "properties": { "any_of": { "type": "array", "description": "Array of tags where at least one must be present in the uploaded file.", "items": { "type": "string" }, "example": ["research-report", "any-tag"] } }, "required": ["any_of"] }, "document": { "type": "object", "description": "Document filter to restrict the search to a list of specified documents. Use document IDs (e.g., from a previous search response) to search only within those documents.", "properties": { "mode": { "type": "string", "description": "Filter mode for document selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["3C54E042B2B19B244F57D3C6415439D1"] } }, "required": ["mode", "values"] }, "chunk": { "type": "object", "description": "Chunk filter to narrow the search to a particular section within the document. Use when expanding the context of a previously retrieved chunk (e.g., from the 3rd chunk to the 7th). Useful to expand context around a chunk that was previously retrieved. Chunk indices are 1-based.", "properties": { "from": { "type": "integer", "description": "1-based index of the first chunk to include in the search range.", "example": 3 }, "to": { "type": "integer", "description": "1-based index of the last chunk to include in the search range (inclusive).", "example": 7 } }, "required": ["from", "to"] } } }, "auto_enrich_filters": { "type": "boolean", "description": "Advanced parameter that controls automatic enrichment of filters using the query text. When set to true (default), the system automatically extracts and adds relevant filter values from the query text. Set to false when you have created a strict query with specific keywords and entity filters and you do not want any extra values added to those filters." } } }, "group_by": { "type": "array", "description": "Break the volume down by where the matching documents come from. Any combination of `source`, `tier`. `package` also supported for enterprise users on unit-based consumption model.", "items": { "type": "string", "enum": ["source", "tier", "package"] }, "minItems": 1, "uniqueItems": true, "example": ["source"] } }, "required": ["query"], "example": { "query": { "text": "Type a theme to get volume stats...." } } } } } }, "responses": { "200": { "description": "Volume search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "object", "description": "Volume statistics aggregated by date and totals.", "properties": { "volume": { "type": "array", "description": "Array of volume statistics for each date in the time range.", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date in YYYY-MM-DD format.", "example": "2025-01-01" }, "documents": { "type": "integer", "description": "Number of documents matching the query on this date.", "example": 164 }, "chunks": { "type": "integer", "description": "Number of chunks matching the query on this date.", "example": 387 }, "sentiment": { "type": "number", "format": "float", "description": "Average sentiment score for chunks on this date, ranging from -1.00 to 1.00.", "example": -0.15 } }, "required": ["date", "documents", "chunks"] } }, "total": { "type": "object", "description": "Aggregated totals across all dates in the time range.", "properties": { "documents": { "type": "integer", "description": "Total number of documents matching the query.", "example": 3440 }, "chunks": { "type": "integer", "description": "Total number of chunks matching the query.", "example": 8196 }, "sentiment": { "type": "number", "format": "float", "description": "Average sentiment score across all chunks, ranging from -1.00 to 1.00.", "example": -0.18 } }, "required": ["documents", "chunks"] }, "groups": { "type": "object", "description": "Present only when `group_by` was sent. Contains one list per requested value, each sorted by `chunks` descending.", "properties": { "sources": { "type": "array", "description": "One row per source, at most 1,000 rows (the most recently active sources are kept). Present when `group_by` includes `source`.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Bigdata source id, as used by the `source` filter.", "example": "B1A50F" }, "documents": { "type": "integer", "description": "Number of distinct documents in this group.", "example": 58 }, "chunks": { "type": "integer", "description": "Number of chunks in this group.", "example": 130 } }, "required": ["id", "documents", "chunks"] } }, "tiers": { "type": "array", "description": "One row per content tier. Present when `group_by` includes `tier`.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Content tier, one of `premium-news`, `corporate-communications`, `expert-interviews`, `earnings-transcripts`, `regulatory-filings`, `podcasts`, `web` or `private-data`.", "example": "premium-news" }, "documents": { "type": "integer", "description": "Number of distinct documents in this group.", "example": 412 }, "chunks": { "type": "integer", "description": "Number of chunks in this group.", "example": 889 } }, "required": ["id", "documents", "chunks"] } }, "packages": { "type": "array", "description": "One row per content package. A document can belong to several packages, so counts may overlap and do not add up to the totals. Present when `group_by` includes `package` (enterprise users on unit-based consumption model).", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Package, as shown in the Bigdata Store", "example": "public" }, "documents": { "type": "integer", "description": "Number of distinct documents in this group.", "example": 672 }, "chunks": { "type": "integer", "description": "Number of chunks in this group.", "example": 889 } }, "required": ["id", "documents", "chunks"] } } } } }, "required": ["volume", "total"] }, "metadata": { "type": "object", "description": "Request metadata and timing information.", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request.", "example": "473d22ea-7753-41d8-825a-4a4c7696f8cb" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the response was generated.", "example": "2025-12-15T17:34:34.181589+00:00" } }, "required": ["request_id", "timestamp"] }, "usage": { "$ref": "#/components/schemas/AggregateSearchUsage" } }, "required": ["results", "usage"] } } } } } } }, "/v1/search/watchlist": { "post": { "tags": [ "Search" ], "summary": "Search watchlist", "operationId": "search_watchlist", "description": "Search an entire watchlist and get results grouped by entity.\n\nUnlike `/v1/search`, where a few entities can dominate the results, watchlist search distributes results more evenly across your watchlist. You can choose how chunks are allocated:\n\n- `max_chunks.per_entity: false` \u2013 split a total chunk budget across all entities.\n- `max_chunks.per_entity: true` \u2013 return up to a fixed number of chunks for each entity.\n\nThe response contains one group for every requested entity, in the same order as the request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "watchlists", "query" ], "properties": { "search_mode": { "type": "string", "enum": [ "fast" ], "default": "fast", "description": "Search mode. Only `fast` is available for watchlist search." }, "watchlists": { "type": "array", "description": "Entities to group the results by. Each item is a set of entity ids searched with the same scope.", "items": { "type": "object", "required": [ "entities" ], "properties": { "entities": { "type": "array", "description": "Entity identifiers from the Knowledge Graph (alphanumeric, at most 64 characters). Use the Knowledge Graph endpoints to resolve companies, people, places and other entities to their ids.", "items": { "type": "string" }, "example": [ "228D42", "D8442A" ] }, "scope": { "type": "string", "enum": [ "all", "headline", "body" ], "default": "all", "description": "Where an entity must be detected for a chunk to count for it: anywhere in the document (`all`), in the headline (`headline`) or in the chunk text (`body`)." } } } }, "max_chunks": { "type": "object", "required": [ "value" ], "description": "How many chunks to return and how to distribute them across the watchlist. When omitted, 100 chunks in total are spread across the entities.", "properties": { "value": { "type": "integer", "minimum": 1, "example": 5, "description": "Number of chunks. With `per_entity: false` it is the total across all entities: up to 512 while the reranker is enabled (the default), up to 1000 with `ranking_params.reranker.enabled: false`. With `per_entity: true` it applies to every entity (1-100), and `entities × value` must not exceed 4000." }, "per_entity": { "type": "boolean", "default": false, "description": "`false`: `value` is a total budget shared by the watchlist, allocated to the entities with the most relevant matches. `true`: up to `value` chunks are returned for every entity." } } }, "query": { "type": "object", "description": "The search run for every entity in the watchlist. Provide at least one of `text` or `filters`.\n\nUnlike `/v1/search`, `max_chunks`, `texts` and `external_search` are not accepted inside `query`.", "properties": { "text": { "type": "string", "minLength": 4, "maxLength": 1400, "description": "Natural-language search string, run for every entity in the watchlist. Optional when `filters` are provided.", "example": "supply chain disruptions" }, "filters": { "type": "object", "properties": { "timestamp": { "type": "object", "description": "Temporal filter to retrieve documents with a timestamp within a start and end date.", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')" }, "end": { "type": "string", "format": "date-time", "description": "End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')" } } }, "document_type": { "type": "object", "description": "Document type filter to retrieve documents of specific types. Values can be either plain strings (deprecated) or objects with 'type' and optional 'subtypes' for more precise filtering.", "properties": { "mode": { "type": "string", "description": "Filter mode for document type selection.", "enum": [ "INCLUDE", "EXCLUDE" ] }, "values": { "type": "array", "description": "Array of document type values to include or exclude based on the mode. Each value can be a string (deprecated) or an object with 'type' and optional 'subtypes'.", "items": { "oneOf": [ { "type": "object", "description": "Document type object with type and optional subtypes for more precise filtering.", "properties": { "type": { "type": "string", "enum": [ "NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH" ], "description": "The document type." }, "subtypes": { "type": "array", "description": "Optional array of subtypes for more specific filtering. Supported subtypes vary by type:\nFor [FILING](/getting-started/search/query_filters#filing): SEC_10_K, SEC_10_Q, SEC_8_K, SEC_20_F, SEC_S_1, SEC_S_3, SEC_6_K, SEC_424B2, SEC_DEF_14A, SEC_485APOS, SEC_485BPOS, SEC_497, SEC_497AD, SEC_497J, SEC_497K, SEC_497VPI, SEC_497VPSUB, SEC_497VPU, SEC_N_CSR, SEC_N_CSR_A, SEC_N_CSRS, SEC_N_CSRS_A, SEC_NPORT_P_A, SEC_NT_NCSR, SEC_NT_NCSR_A, SEC_NT_NPORT_P, SEC_NTFNCSR.\n\nFor [TRANSCRIPT and TRANSCRIPT-PRESENTATION](/getting-started/search/query_filters#transcript): ANALYST_INVESTOR_SHAREHOLDER_MEETING, CONFERENCE_CALL, GENERAL_PRESENTATION, EARNINGS_CALL, EARNINGS_RELEASE, GUIDANCE_CALL, SALES_REVENUE_CALL, SALES_REVENUE_RELEASE, SPECIAL_SITUATION_MA, SHAREHOLDERS_MEETING, MANAGEMENT_PLAN_ANNOUNCEMENT, INVESTOR_CONFERENCE_CALL.\n\nFor [INVESTMENT-RESEARCH](/getting-started/search/query_filters#investment-research): COMPANY_REPORT, COVERAGE_ANALYSIS, ECONOMIC_REPORT, FIXED_INCOME_REPORT, FUND_REPORT, FX_AND_DERIVATIVES_REPORT, GENERIC_REPORT, INDEX_REPORT, INDUSTRY_REPORT, MARKET_UPDATE, PORTFOLIO_STRATEGY, PORTFOLIO_SUMMARY, RATING_REPORT, RESEARCH_NOTE, THEMATIC_ANALYSIS.", "items": { "type": "string", "enum": [ "SEC_10_K", "SEC_10_Q", "SEC_8_K", "SEC_20_F", "SEC_S_1", "SEC_S_3", "SEC_6_K", "SEC_424B2", "SEC_DEF_14A", "SEC_485APOS", "SEC_485BPOS", "SEC_497", "SEC_497AD", "SEC_497J", "SEC_497K", "SEC_497VPI", "SEC_497VPSUB", "SEC_497VPU", "SEC_N_CSR", "SEC_N_CSR_A", "SEC_N_CSRS", "SEC_N_CSRS_A", "SEC_NPORT_P_A", "SEC_NT_NCSR", "SEC_NT_NCSR_A", "SEC_NT_NPORT_P", "SEC_NTFNCSR", "ANALYST_INVESTOR_SHAREHOLDER_MEETING", "CONFERENCE_CALL", "GENERAL_PRESENTATION", "EARNINGS_CALL", "EARNINGS_RELEASE", "GUIDANCE_CALL", "SALES_REVENUE_CALL", "SALES_REVENUE_RELEASE", "SPECIAL_SITUATION_MA", "SHAREHOLDERS_MEETING", "MANAGEMENT_PLAN_ANNOUNCEMENT", "INVESTOR_CONFERENCE_CALL", "COMPANY_REPORT", "COVERAGE_ANALYSIS", "ECONOMIC_REPORT", "FIXED_INCOME_REPORT", "FUND_REPORT", "FX_AND_DERIVATIVES_REPORT", "GENERIC_REPORT", "INDEX_REPORT", "INDUSTRY_REPORT", "MARKET_UPDATE", "PORTFOLIO_STRATEGY", "RATING_REPORT", "RESEARCH_NOTE", "THEMATIC_ANALYSIS", "PORTFOLIO_SUMMARY" ] } } }, "required": [ "type" ] }, { "type": "string", "enum": [ "NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH" ], "deprecated": true, "description": "Deprecated: Use the object format with 'type' and optional 'subtypes' instead." } ] } } }, "required": [ "mode", "values" ] }, "original_language": { "type": "object", "description": "Original language filter to retrieve documents based on the language in which the content was originally published. Documents remain searchable in English regardless of their original language: this filter selects on the source language, not on the language of the text returned.", "properties": { "mode": { "type": "string", "description": "Filter mode for original language selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of original languages to include or exclude based on the mode. Values are lowercase ISO 639-1 codes, for example `en`, `de` or `ja`, with `zh-Hans` and `zh-Hant` for Simplified and Traditional Chinese. Values are not validated against a fixed list, as new original languages are onboarded over time.", "items": { "type": "string" }, "example": ["de", "ja"] } }, "required": ["mode", "values"] }, "source": { "type": "object", "description": "Source filter to retrieve documents from specific sources.", "properties": { "mode": { "type": "string", "description": "Filter mode for source selection.", "enum": [ "INCLUDE", "EXCLUDE" ] }, "values": { "type": "array", "description": "Array of source IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": [ "ED68DC" ] } }, "required": [ "mode", "values" ] }, "category": { "type": "object", "description": "Category filter to retrieve documents from specific categories. This enables selecting a related set of sources without having to add a long list of source IDs.", "properties": { "mode": { "type": "string", "description": "Filter mode for category selection.", "enum": [ "INCLUDE", "EXCLUDE" ] }, "values": { "type": "array", "description": "Array of categories to include or exclude based on the mode.", "items": { "type": "string", "enum": [ "expert_interviews", "filings", "my_files", "news", "news_premium", "news_public", "podcasts", "research", "research_academic_journals", "research_investment_research", "transcripts" ] } } }, "required": [ "mode", "values" ] }, "tier": { "type": "object", "description": "Content tier filter to retrieve documents from specific content tiers. Tiers are how content is packaged and priced under the token-based consumption model.", "properties": { "mode": { "type": "string", "description": "Filter mode for content tier selection.", "enum": [ "INCLUDE", "EXCLUDE" ] }, "values": { "type": "array", "description": "Array of content tiers to include or exclude based on the mode.", "items": { "type": "string", "enum": [ "corporate-communications", "premium-news", "expert-interviews", "earnings-transcripts", "regulatory-filings", "podcasts", "web", "private-data" ] } } }, "required": [ "mode", "values" ] }, "keyword": { "type": "object", "description": "Keyword filter to retrieve chunks based on keyword presence.", "properties": { "search_in": { "type": "string", "enum": [ "HEADLINE", "BODY", "ALL" ], "description": "Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of keywords that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of keywords where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [] }, "none_of": { "type": "array", "description": "Array of keywords that must not be present in the chunk.", "items": { "type": "string" }, "example": [ "operating" ] } }, "required": [ "all_of", "any_of", "none_of" ] }, "entity": { "type": "object", "description": "Entity filter to retrieve chunks where entities were identified.", "properties": { "search_in": { "type": "string", "enum": [ "HEADLINE", "BODY", "ALL" ], "description": "Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of entity IDs that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of entity IDs where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [ "228D42" ] }, "none_of": { "type": "array", "description": "Array of entity IDs that must not be present in the document.", "items": { "type": "string" }, "example": [] } }, "required": [ "all_of", "any_of", "none_of" ] }, "sentiment": { "type": "object", "description": "Sentiment filter to retrieve chunks based on sentiment score. All chunks contain a sentiment score ranging from -1.00 to 1.00, indicating how that chunk might impact the market and whether it will have a positive or negative effect.", "properties": { "ranges": { "type": "array", "description": "Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.", "items": { "type": "object", "properties": { "min": { "type": "number", "format": "float", "description": "Minimum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -1.0 }, "max": { "type": "number", "format": "float", "description": "Maximum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -0.3 } }, "required": [ "min", "max" ] }, "example": [ { "min": -1.0, "max": -0.3 }, { "min": 0.3, "max": 1.0 } ] }, "values": { "type": "array", "description": "Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering.", "deprecated": true, "items": { "type": "string", "enum": [ "positive", "negative", "neutral" ], "description": "Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1)" } } } }, "reporting_entities": { "type": "array", "description": "Select one or multiple companies for which the returned documents must have been reported by.", "items": { "type": "string" }, "example": [ "228D42" ] }, "reporting_periods": { "type": "array", "description": "Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).", "items": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "description": "Fiscal year", "example": 2024 }, "fiscal_quarter": { "type": "integer", "description": "Fiscal quarter (1-4)", "minimum": 1, "maximum": 4, "example": 3 } }, "required": [ "fiscal_year", "fiscal_quarter" ] }, "example": [ { "fiscal_year": 2024, "fiscal_quarter": 3 } ] }, "topic": { "type": "object", "description": "Topic filter to retrieve chunks based on topic presence. Example: {\"any_of\": [\"business,stock-prices,stock-price-volatility,down,\"]} to find documents about stock price volatility.", "properties": { "search_in": { "type": "string", "enum": [ "HEADLINE", "BODY", "ALL" ], "description": "Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of topics that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of topics where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [ "business,stock-prices,stock-price-volatility,down," ] }, "none_of": { "type": "array", "description": "Array of topics that must not be present in the chunk.", "items": { "type": "string" }, "example": [] } }, "required": [ "all_of", "any_of", "none_of" ] }, "authors": { "type": "object", "description": "Filter by document author. Useful for investment research.", "properties": { "type": { "type": "string", "enum": [ "company", "person", "position" ], "description": "`person` for individuals, `company` for firms, or `position` for roles." }, "values": { "type": "array", "description": "Entity IDs to filter by.", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "type", "values" ], "example": { "type": "person", "values": [ "4L0FDS" ] } }, "speakers": { "type": "object", "description": "Filter by speaker. Useful for transcripts and expert interviews.", "properties": { "type": { "type": "string", "enum": [ "company", "person", "position" ], "description": "`person` for individuals, `company` for firms, or `position` for roles." }, "values": { "type": "array", "description": "Entity IDs to filter by.", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "type", "values" ], "example": { "type": "company", "values": [ "DF67D7" ] } }, "sections": { "type": "object", "description": "Section filter to restrict transcript and expert interview results to specific sections.", "properties": { "any_of": { "type": "array", "description": "Array of transcript sections where at least one must be present. Values are case-insensitive.", "items": { "type": "string", "enum": [ "MANAGEMENT-DISCUSSION", "QUESTION-ANSWER" ] }, "example": ["QUESTION-ANSWER"] } }, "required": ["any_of"] }, "tag": { "type": "object", "description": "Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.", "properties": { "any_of": { "type": "array", "description": "Array of tags where at least one must be present in the uploaded file.", "items": { "type": "string" }, "example": [ "research-report", "any-tag" ] } }, "required": [ "any_of" ] }, "document": { "type": "object", "description": "Document filter to restrict the search to a list of specified documents. Use document IDs (e.g., from a previous search response) to search only within those documents.", "properties": { "mode": { "type": "string", "description": "Filter mode for document selection.", "enum": [ "INCLUDE", "EXCLUDE" ] }, "values": { "type": "array", "description": "Array of document IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": [ "3C54E042B2B19B244F57D3C6415439D1" ] } }, "required": [ "mode", "values" ] }, "chunk": { "type": "object", "description": "Chunk filter to narrow the search to a particular section within the document. Use when expanding the context of a previously retrieved chunk (e.g., from the 3rd chunk to the 7th). Useful to expand context around a chunk that was previously retrieved. Chunk indices are 1-based.", "properties": { "from": { "type": "integer", "description": "1-based index of the first chunk to include in the search range.", "example": 3 }, "to": { "type": "integer", "description": "1-based index of the last chunk to include in the search range (inclusive).", "example": 7 } }, "required": [ "from", "to" ] } } }, "ranking_params": { "type": "object", "description": "Groups parameters that affect the ranking algorithm and determine chunk relevance. Content diversification is always enabled for watchlist search and cannot be configured here.", "properties": { "source_boost": { "type": "number", "format": "float", "description": "Controls how much the source rank influences relevance. Range: 0-10. Default: 1.0. 0 → source rank has no effect. 10 → maximum effect, boosting chunks from premium sources.", "minimum": 0, "maximum": 10, "example": 1.0 }, "freshness_boost": { "type": "number", "format": "float", "description": "Controls the influence of document timestamp on relevance. Range: 0-10. Default: 1.0. 0 → publishing time is ignored (useful for point-in-time research). 10 → most recent documents are heavily prioritized.", "minimum": 0, "maximum": 10, "example": 1.0 }, "reranker": { "type": "object", "description": "Applies a second ranking phase to improve precision. A cross-encoder model re-ranks the top candidates using the input query.", "properties": { "enabled": { "type": "boolean", "description": "Enable the re-ranker. True by default." }, "threshold": { "type": "number", "format": "float", "description": "Reranker threshold to filter results by relevance score. Range: 0.0 to 1.0. The default reranker uses a threshold of 0.2, but you can set a custom threshold to improve precision and reduce noise. Higher values return fewer, more relevant results.", "minimum": 0.0, "maximum": 1.0, "example": 0.8 }, "text": { "type": "string", "description": "Custom text for the cross-encoder to rank against. By default the reranker uses `query.text`.", "example": "supply chain impact on manufacturing" } }, "required": [ "enabled" ] } } }, "auto_enrich_filters": { "type": "boolean", "description": "Advanced parameter that controls automatic enrichment of filters using the query text. When set to true (default), the system automatically extracts and adds relevant filter values from the query text. Set to false when you have created a strict query with specific keywords and entity filters and you do not want any extra values added to those filters." } } } } } } } }, "responses": { "200": { "description": "Search results grouped per watchlist entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "One group per requested entity, in request order. Entities without matches have an empty `documents` array.", "items": { "type": "object", "required": [ "entity_id", "documents" ], "properties": { "entity_id": { "type": "string", "description": "The watchlist entity identifier.", "example": "228D42" }, "documents": { "type": "array", "description": "Documents whose chunks were assigned to this entity.", "items": { "type": "object", "required": [ "id", "headline", "chunks" ], "properties": { "id": { "type": "string", "description": "Unique document identifier, a 32-character hexadecimal string.", "example": "57BB2AD919...." }, "headline": { "type": "string", "description": "Document title.", "example": "Headline example: Microsoft Corp.: Q3 2025 Earnings Call" }, "timestamp": { "type": "string", "format": "date-time", "description": "Document timestamp in ANSI format and UTC timezone.", "example": "2025-04-30T21:30:00Z" }, "url": { "type": "string", "description": "URL of the document.", "example": "https://www.benzinga.com/node/45117886?utm_campaign=partner_feed&utm_medium=feed&utm_source=ravenpack" }, "chunks": { "type": "array", "description": "Chunks of this document assigned to the entity. A chunk is never returned under two entities.", "items": { "type": "object", "required": [ "cnum", "text", "relevance" ], "properties": { "cnum": { "type": "integer", "description": "The index of the chunk in the document. You can use it to sort them in order. The first document chunk has cnum with the value 1.", "example": 7 }, "text": { "type": "string", "description": "The text of the chunk.", "example": "Microsoft will provide forward-looking guidance on its earnings conference call Wednesday, which can be viewed below.\nMSFT Price Action: Microsoft stock is up 5.5% to $417.17 year-over-year in after-hours trading Wednesday versus a 52-week trading range of $344.79 to $468.35." }, "relevance": { "type": "number", "format": "float", "description": "A float between 0 and 1. Relevance indicates the degree to which a particular match aligns with the various terms in your query. It's important to note that the relevance scores you receive are only meaningful within the context of the same search. Each execution generates unique scores, so comparing relevance across different queries is not meaningful.", "example": 0.8949412447701082 }, "rerank_relevance": { "type": "number", "format": "float", "nullable": true, "description": "Cross-encoder relevance of the chunk for the query, between 0 and 1. Informational; `null` when the reranker did not score the chunk.", "example": 0.6432 } } } } } } } } } }, "usage": { "$ref": "#/components/schemas/SearchUsage" }, "metadata": { "type": "object", "description": "Request metadata and timing information.", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request.", "example": "user_2k3Z4SerTUIieyCfQhGR5UF2Af3" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the response was generated.", "example": "2025-09-12T11:10:46.019077+00:00" } }, "required": [ "request_id", "timestamp" ] } } } } } } } } }, "/v1/search/batches": { "post": { "tags": [ "Batch Search" ], "summary": "Create a Batch Job", "description": "Process large volumes of requests asynchronously.\n\nBatch Search provides a simple set of endpoints to initiate batch processing jobs, monitor progress as requests are executed, and collect results once processing completes.\n\nEach batch begins with a `.jsonl` file where every line represents an individual Search request.\n\nOnce your input file is ready, call the following endpoint to obtain a `batch_id` and `presigned_url`.\n\nCopy the `presigned_url` from the response. You will need this URL to [upload your input file](/api-reference/batch-search/upload-your-input-file).\n\nFor a step-by-step walkthrough, see the [Batch Search how-to guide](/how-to-guides/search/batch_search).", "operationId": "create_batch_job_v1_search_batches_post", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJobUploadResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/s3_upload_placeholder": { "put": { "tags": [ "Batch Search" ], "summary": "Upload Your Input File", "description": "Now that you have created your batch job, use the `presigned_url` to upload your `.jsonl` file directly to the designated storage location using the following command:\n\n```shell\ncurl --request PUT \\\n --url '' \\\n --header 'Content-Type: application/jsonl' \\\n --data-binary '@your_input_file.jsonl'\n```\n\nReplace `` with the `presigned_url` and `@your_input_file.jsonl` with the path to your actual file.\n\nFor a step-by-step walkthrough, see the [Batch Search how-to guide](/how-to-guides/search/batch_search).", "operationId": "upload_batch_file_s3", "security": [], "x-mint": { "metadata": { "playground": "none" } }, "x-code-samples": [ { "lang": "sh", "label": "Terminal", "source": "curl --request PUT \\\n --url '' \\\n --header 'Content-Type: application/jsonl' \\\n --data-binary '@your_input_file.jsonl'" } ], "responses": { "200": { "description": "S3 returns 200 OK" } } } }, "/v1/search/batches/{batch_id}": { "get": { "tags": [ "Batch Search" ], "summary": "Get Batch Job Info", "description": "Check the status of your batch job and retrieve results when processing is complete.\n\n- `batch_id`: Your job's unique identifier\n- `status`: Current processing state (pending, processing, completed, failed, or cancelled)\n- `estimated_completion_time`: A dynamic ISO 8601 timestamp indicating when the job is expected to finish. This adjusts in real-time based on system throughput and queue backlog.\n- `output_file_url`: Download link for your results (available when status is completed)\n\nOnce your batch reaches `completed` status, use the `output_file_url` to download a `.jsonl` file containing all results via a simple GET request.\n\nEach line in your results file contains:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| line_number | int | Matches the line number from your original input file |\n| status | string | Result status: success, error, timeout, or exception |\n| query | object | The original search query you submitted |\n| response | object | The Search response for this query |\n| code | int | HTTP status code |\n| error | string | Error description (only present if request failed) |\n\nFor a step-by-step walkthrough, see the [Batch Search how-to guide](/how-to-guides/search/batch_search).", "operationId": "get_batch_job_info_v1_search_batches__batch_id__get", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Batch Id" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJobStatusResponse" } } } }, "400": { "description": "Bad Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/search/co-mentions/entities": { "post": { "tags": ["Co-mentions"], "summary": "Connected Entities", "operationId": "search_co_mentions_entities", "description": "Explore entities associated with your search filters to reveal deeper connections. This endpoint retrieves the top N entities ranked by chunk volume and headline volume, merges the two sets, and returns entities with combined or individual counts. Timestamp ranges are limited to one year; for longer periods, split into successive one-year requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "Provide at least one of `text`, `texts` or `filters`.", "properties": { "text": { "type": "string", "description": "Natural-language search string. Optional when `texts` or `filters` are provided. Mutually exclusive with `texts`.", "example": "Tariffs impact in China" }, "texts": { "type": "array", "description": "Multiple natural-language search strings (max 5). Use when a single query cannot capture all aspects of your intent. Mutually exclusive with `text`.", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "example": ["supply chain disruptions", "logistics delays", "shipping bottlenecks"] }, "filters": { "type": "object", "properties": { "timestamp": { "type": "object", "description": "Temporal filter to retrieve documents with a timestamp within a start and end date. On this endpoint, `start` and `end` can be at most one year apart. Cover longer periods with multiple requests.", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')" }, "end": { "type": "string", "format": "date-time", "description": "End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')" } } }, "document_type": { "type": "object", "description": "Document type filter to retrieve documents of specific types. Values can be either plain strings (deprecated) or objects with 'type' and optional 'subtypes' for more precise filtering.", "properties": { "mode": { "type": "string", "description": "Filter mode for document type selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document type values to include or exclude based on the mode. Each value can be a string (deprecated) or an object with 'type' and optional 'subtypes'.", "items": { "oneOf": [ { "type": "object", "description": "Document type object with type and optional subtypes for more precise filtering.", "properties": { "type": { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "description": "The document type." }, "subtypes": { "type": "array", "description": "Optional array of subtypes for more specific filtering. Supported subtypes vary by type:\nFor [FILING](/getting-started/search/query_filters#filing): SEC_10_K, SEC_10_Q, SEC_8_K, SEC_20_F, SEC_S_1, SEC_S_3, SEC_6_K, SEC_424B2, SEC_DEF_14A, SEC_485APOS, SEC_485BPOS, SEC_497, SEC_497AD, SEC_497J, SEC_497K, SEC_497VPI, SEC_497VPSUB, SEC_497VPU, SEC_N_CSR, SEC_N_CSR_A, SEC_N_CSRS, SEC_N_CSRS_A, SEC_NPORT_P_A, SEC_NT_NCSR, SEC_NT_NCSR_A, SEC_NT_NPORT_P, SEC_NTFNCSR.\n\nFor [TRANSCRIPT and TRANSCRIPT-PRESENTATION](/getting-started/search/query_filters#transcript): ANALYST_INVESTOR_SHAREHOLDER_MEETING, CONFERENCE_CALL, GENERAL_PRESENTATION, EARNINGS_CALL, EARNINGS_RELEASE, GUIDANCE_CALL, SALES_REVENUE_CALL, SALES_REVENUE_RELEASE, SPECIAL_SITUATION_MA, SHAREHOLDERS_MEETING, MANAGEMENT_PLAN_ANNOUNCEMENT, INVESTOR_CONFERENCE_CALL.\n\nFor [INVESTMENT-RESEARCH](/getting-started/search/query_filters#investment-research): COMPANY_REPORT, COVERAGE_ANALYSIS, ECONOMIC_REPORT, FIXED_INCOME_REPORT, FUND_REPORT, FX_AND_DERIVATIVES_REPORT, GENERIC_REPORT, INDEX_REPORT, INDUSTRY_REPORT, MARKET_UPDATE, PORTFOLIO_STRATEGY, PORTFOLIO_SUMMARY, RATING_REPORT, RESEARCH_NOTE, THEMATIC_ANALYSIS.", "items": { "type": "string", "enum": [ "SEC_10_K", "SEC_10_Q", "SEC_8_K", "SEC_20_F", "SEC_S_1", "SEC_S_3", "SEC_6_K", "SEC_424B2", "SEC_DEF_14A", "SEC_485APOS", "SEC_485BPOS", "SEC_497", "SEC_497AD", "SEC_497J", "SEC_497K", "SEC_497VPI", "SEC_497VPSUB", "SEC_497VPU", "SEC_N_CSR", "SEC_N_CSR_A", "SEC_N_CSRS", "SEC_N_CSRS_A", "SEC_NPORT_P_A", "SEC_NT_NCSR", "SEC_NT_NCSR_A", "SEC_NT_NPORT_P", "SEC_NTFNCSR", "ANALYST_INVESTOR_SHAREHOLDER_MEETING", "CONFERENCE_CALL", "GENERAL_PRESENTATION", "EARNINGS_CALL", "EARNINGS_RELEASE", "GUIDANCE_CALL", "SALES_REVENUE_CALL", "SALES_REVENUE_RELEASE", "SPECIAL_SITUATION_MA", "SHAREHOLDERS_MEETING", "MANAGEMENT_PLAN_ANNOUNCEMENT", "INVESTOR_CONFERENCE_CALL", "COMPANY_REPORT", "COVERAGE_ANALYSIS", "ECONOMIC_REPORT", "FIXED_INCOME_REPORT", "FUND_REPORT", "FX_AND_DERIVATIVES_REPORT", "GENERIC_REPORT", "INDEX_REPORT", "INDUSTRY_REPORT", "MARKET_UPDATE", "PORTFOLIO_STRATEGY", "RATING_REPORT", "RESEARCH_NOTE", "THEMATIC_ANALYSIS", "PORTFOLIO_SUMMARY" ] } } }, "required": ["type"] }, { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "deprecated": true, "description": "Deprecated: Use the object format with 'type' and optional 'subtypes' instead." } ] } } }, "required": ["mode", "values"] }, "original_language": { "type": "object", "description": "Original language filter to retrieve documents based on the language in which the content was originally published. Documents remain searchable in English regardless of their original language: this filter selects on the source language, not on the language of the text returned.", "properties": { "mode": { "type": "string", "description": "Filter mode for original language selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of original languages to include or exclude based on the mode. Values are lowercase ISO 639-1 codes, for example `en`, `de` or `ja`, with `zh-Hans` and `zh-Hant` for Simplified and Traditional Chinese. Values are not validated against a fixed list, as new original languages are onboarded over time.", "items": { "type": "string" }, "example": ["de", "ja"] } }, "required": ["mode", "values"] }, "source": { "type": "object", "description": "Source filter to retrieve documents from specific sources.", "properties": { "mode": { "type": "string", "description": "Filter mode for source selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of source IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["ED68DC"] } }, "required": ["mode", "values"] }, "category": { "type": "object", "description": "Category filter to retrieve documents from specific categories. This enables selecting a related set of sources without having to add a long list of source IDs.", "properties": { "mode": { "type": "string", "description": "Filter mode for category selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of categories to include or exclude based on the mode.", "items": { "type": "string", "enum": ["expert_interviews", "filings", "my_files", "news", "news_premium", "news_public", "podcasts", "research", "research_academic_journals", "research_investment_research", "transcripts"] } } }, "required": ["mode", "values"] }, "tier": { "type": "object", "description": "Content tier filter to retrieve documents from specific content tiers. Tiers are how content is packaged and priced under the token-based consumption model.", "properties": { "mode": { "type": "string", "description": "Filter mode for content tier selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of content tiers to include or exclude based on the mode.", "items": { "type": "string", "enum": [ "corporate-communications", "premium-news", "expert-interviews", "earnings-transcripts", "regulatory-filings", "podcasts", "web", "private-data" ] } } }, "required": ["mode", "values"] }, "keyword": { "type": "object", "description": "Keyword filter to retrieve chunks based on keyword presence.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of keywords that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of keywords where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [] }, "none_of": { "type": "array", "description": "Array of keywords that must not be present in the chunk.", "items": { "type": "string" }, "example": ["operating"] } }, "required": ["all_of", "any_of", "none_of"] }, "entity": { "type": "object", "description": "Entity filter to retrieve chunks where entities were identified.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of entity IDs that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of entity IDs where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["228D42"] }, "none_of": { "type": "array", "description": "Array of entity IDs that must not be present in the document.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sentiment": { "type": "object", "description": "Sentiment filter to retrieve chunks based on sentiment score. All chunks contain a sentiment score ranging from -1.00 to 1.00, indicating how that chunk might impact the market and whether it will have a positive or negative effect.", "properties": { "ranges": { "type": "array", "description": "Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.", "items": { "type": "object", "properties": { "min": { "type": "number", "format": "float", "description": "Minimum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -1.0 }, "max": { "type": "number", "format": "float", "description": "Maximum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -0.3 } }, "required": ["min", "max"] }, "example": [ { "min": -1.0, "max": -0.3 }, { "min": 0.3, "max": 1.0 } ] }, "values": { "type": "array", "description": "Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering.", "deprecated": true, "items": { "type": "string", "enum": ["positive", "negative", "neutral"], "description": "Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1)" } } } }, "reporting_entities": { "type": "array", "description": "Select one or multiple companies for which the returned documents must have been reported by.", "items": { "type": "string" }, "example": ["228D42"] }, "reporting_periods": { "type": "array", "description": "Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).", "items": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "description": "Fiscal year", "example": 2024 }, "fiscal_quarter": { "type": "integer", "description": "Fiscal quarter (1-4)", "minimum": 1, "maximum": 4, "example": 3 } }, "required": ["fiscal_year", "fiscal_quarter"] }, "example": [ { "fiscal_year": 2024, "fiscal_quarter": 3 } ] }, "topic": { "type": "object", "description": "Topic filter to retrieve chunks based on topic presence. Example: {\"any_of\": [\"business,stock-prices,stock-price-volatility,down,\"]} to find documents about stock price volatility.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of topics that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of topics where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["business,stock-prices,stock-price-volatility,down,"] }, "none_of": { "type": "array", "description": "Array of topics that must not be present in the chunk.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sections": { "type": "object", "description": "Section filter to restrict transcript and expert interview results to specific sections.", "properties": { "any_of": { "type": "array", "description": "Array of transcript sections where at least one must be present. Values are case-insensitive.", "items": { "type": "string", "enum": [ "MANAGEMENT-DISCUSSION", "QUESTION-ANSWER" ] }, "example": ["QUESTION-ANSWER"] } }, "required": ["any_of"] }, "tag": { "type": "object", "description": "Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.", "properties": { "any_of": { "type": "array", "description": "Array of tags where at least one must be present in the uploaded file.", "items": { "type": "string" }, "example": ["research-report", "any-tag"] } }, "required": ["any_of"] }, "document": { "type": "object", "description": "Document filter to restrict the search to a list of specified documents. Use document IDs (e.g., from a previous search response) to search only within those documents.", "properties": { "mode": { "type": "string", "description": "Filter mode for document selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["3C54E042B2B19B244F57D3C6415439D1"] } }, "required": ["mode", "values"] }, "chunk": { "type": "object", "description": "Chunk filter to narrow the search to a particular section within the document. Use when expanding the context of a previously retrieved chunk (e.g., from the 3rd chunk to the 7th). Useful to expand context around a chunk that was previously retrieved. Chunk indices are 1-based.", "properties": { "from": { "type": "integer", "description": "1-based index of the first chunk to include in the search range.", "example": 3 }, "to": { "type": "integer", "description": "1-based index of the last chunk to include in the search range (inclusive).", "example": 7 } }, "required": ["from", "to"] } } }, "auto_enrich_filters": { "type": "boolean", "description": "Advanced parameter that controls automatic enrichment of filters using the query text. When set to true (default), the system automatically extracts and adds relevant filter values from the query text. Set to false when you have created a strict query with specific keywords and entity filters and you do not want any extra values added to those filters." }, "entity_categories": { "type": "array", "description": "Filter co-mentions by entity category. If not specified, all entity categories are included.", "items": { "type": "string", "enum": ["places", "companies", "organizations", "people", "products", "concepts"] } } } }, "limit": { "type": "integer", "description": "Maximum number of entities to retrieve. It must be lower than or equal to 1000.", "example": 10 } }, "required": ["query"], "example": { "query": { "text": "Type a theme to get connected entities..." } } } } } }, "responses": { "200": { "description": "Entities co-mentions results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "object", "description": "Object containing arrays of different entity types that are co-mentioned with the search query.", "properties": { "places": { "type": "array", "description": "Array of places (countries, cities, regions) co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique entity identifier.", "example": "13FF12" }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this entity appears.", "example": 92468 }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this entity appears.", "example": 24049 } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } }, "companies": { "type": "array", "description": "Array of companies co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique entity identifier.", "example": "275B6C" }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this entity appears.", "example": 0 }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this entity appears.", "example": 105 } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } }, "organizations": { "type": "array", "description": "Array of organizations co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique entity identifier.", "example": "1BC945" }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this entity appears.", "example": 17812 }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this entity appears.", "example": 2427 } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } }, "people": { "type": "array", "description": "Array of people co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique entity identifier.", "example": "22C3AF" }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this entity appears.", "example": 29883 }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this entity appears.", "example": 22536 } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } }, "products": { "type": "array", "description": "Array of products co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique entity identifier." }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this entity appears." }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this entity appears." } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } }, "concepts": { "type": "array", "description": "Array of concepts co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique entity identifier.", "example": "9DB5BD" }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this entity appears.", "example": 106720 }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this entity appears.", "example": 44591 } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } } }, "required": ["places", "companies", "organizations", "people", "products", "concepts"] }, "metadata": { "type": "object", "description": "Request metadata and timing information.", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request.", "example": "0f763fb3-4957-430a-acf6-5d4fc6b5109d" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the response was generated.", "example": "2025-10-02T15:25:28.214117+00:00" } }, "required": ["request_id", "timestamp"] }, "usage": { "$ref": "#/components/schemas/AggregateSearchUsage" } }, "required": ["results", "usage"] } } } } } } }, "/v1/search/co-mentions/topics": { "post": { "tags": ["Co-mentions"], "summary": "Connected Topics", "operationId": "search_co_mentions_topics", "description": "Explore topics associated with your search filters to reveal deeper connections. This endpoint retrieves the top N topics ranked by chunk volume and headline volume, merges the two sets, and returns topics with combined or individual counts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "description": "Provide at least one of `text`, `texts` or `filters`.", "properties": { "text": { "type": "string", "description": "Natural-language search string. Optional when `texts` or `filters` are provided. Mutually exclusive with `texts`.", "example": "Tariffs impact in China" }, "texts": { "type": "array", "description": "Multiple natural-language search strings (max 5). Use when a single query cannot capture all aspects of your intent. Mutually exclusive with `text`.", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "example": ["supply chain disruptions", "logistics delays", "shipping bottlenecks"] }, "filters": { "type": "object", "properties": { "timestamp": { "type": "object", "description": "Temporal filter to retrieve documents with a timestamp within a start and end date. On this endpoint, `start` and `end` can be at most one year apart. Cover longer periods with multiple requests.", "properties": { "start": { "type": "string", "format": "date-time", "description": "Start timestamp in ANSI format and UTC timezone (e.g., '2024-01-01T00:00:00Z')" }, "end": { "type": "string", "format": "date-time", "description": "End timestamp in ANSI format and UTC timezone (e.g., '2024-12-31T23:59:59Z')" } } }, "document_type": { "type": "object", "description": "Document type filter to retrieve documents of specific types. Values can be either plain strings (deprecated) or objects with 'type' and optional 'subtypes' for more precise filtering.", "properties": { "mode": { "type": "string", "description": "Filter mode for document type selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document type values to include or exclude based on the mode. Each value can be a string (deprecated) or an object with 'type' and optional 'subtypes'.", "items": { "oneOf": [ { "type": "object", "description": "Document type object with type and optional subtypes for more precise filtering.", "properties": { "type": { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "description": "The document type." }, "subtypes": { "type": "array", "description": "Optional array of subtypes for more specific filtering. Supported subtypes vary by type:\nFor [FILING](/getting-started/search/query_filters#filing): SEC_10_K, SEC_10_Q, SEC_8_K, SEC_20_F, SEC_S_1, SEC_S_3, SEC_6_K, SEC_424B2, SEC_DEF_14A, SEC_485APOS, SEC_485BPOS, SEC_497, SEC_497AD, SEC_497J, SEC_497K, SEC_497VPI, SEC_497VPSUB, SEC_497VPU, SEC_N_CSR, SEC_N_CSR_A, SEC_N_CSRS, SEC_N_CSRS_A, SEC_NPORT_P_A, SEC_NT_NCSR, SEC_NT_NCSR_A, SEC_NT_NPORT_P, SEC_NTFNCSR.\n\nFor [TRANSCRIPT and TRANSCRIPT-PRESENTATION](/getting-started/search/query_filters#transcript): ANALYST_INVESTOR_SHAREHOLDER_MEETING, CONFERENCE_CALL, GENERAL_PRESENTATION, EARNINGS_CALL, EARNINGS_RELEASE, GUIDANCE_CALL, SALES_REVENUE_CALL, SALES_REVENUE_RELEASE, SPECIAL_SITUATION_MA, SHAREHOLDERS_MEETING, MANAGEMENT_PLAN_ANNOUNCEMENT, INVESTOR_CONFERENCE_CALL.\n\nFor [INVESTMENT-RESEARCH](/getting-started/search/query_filters#investment-research): COMPANY_REPORT, COVERAGE_ANALYSIS, ECONOMIC_REPORT, FIXED_INCOME_REPORT, FUND_REPORT, FX_AND_DERIVATIVES_REPORT, GENERIC_REPORT, INDEX_REPORT, INDUSTRY_REPORT, MARKET_UPDATE, PORTFOLIO_STRATEGY, PORTFOLIO_SUMMARY, RATING_REPORT, RESEARCH_NOTE, THEMATIC_ANALYSIS.", "items": { "type": "string", "enum": [ "SEC_10_K", "SEC_10_Q", "SEC_8_K", "SEC_20_F", "SEC_S_1", "SEC_S_3", "SEC_6_K", "SEC_424B2", "SEC_DEF_14A", "SEC_485APOS", "SEC_485BPOS", "SEC_497", "SEC_497AD", "SEC_497J", "SEC_497K", "SEC_497VPI", "SEC_497VPSUB", "SEC_497VPU", "SEC_N_CSR", "SEC_N_CSR_A", "SEC_N_CSRS", "SEC_N_CSRS_A", "SEC_NPORT_P_A", "SEC_NT_NCSR", "SEC_NT_NCSR_A", "SEC_NT_NPORT_P", "SEC_NTFNCSR", "ANALYST_INVESTOR_SHAREHOLDER_MEETING", "CONFERENCE_CALL", "GENERAL_PRESENTATION", "EARNINGS_CALL", "EARNINGS_RELEASE", "GUIDANCE_CALL", "SALES_REVENUE_CALL", "SALES_REVENUE_RELEASE", "SPECIAL_SITUATION_MA", "SHAREHOLDERS_MEETING", "MANAGEMENT_PLAN_ANNOUNCEMENT", "INVESTOR_CONFERENCE_CALL", "COMPANY_REPORT", "COVERAGE_ANALYSIS", "ECONOMIC_REPORT", "FIXED_INCOME_REPORT", "FUND_REPORT", "FX_AND_DERIVATIVES_REPORT", "GENERIC_REPORT", "INDEX_REPORT", "INDUSTRY_REPORT", "MARKET_UPDATE", "PORTFOLIO_STRATEGY", "RATING_REPORT", "RESEARCH_NOTE", "THEMATIC_ANALYSIS", "PORTFOLIO_SUMMARY" ] } } }, "required": ["type"] }, { "type": "string", "enum": ["NEWS", "TRANSCRIPT", "FILING", "TRANSCRIPT-PRESENTATION", "INVESTMENT-RESEARCH"], "deprecated": true, "description": "Deprecated: Use the object format with 'type' and optional 'subtypes' instead." } ] } } }, "required": ["mode", "values"] }, "original_language": { "type": "object", "description": "Original language filter to retrieve documents based on the language in which the content was originally published. Documents remain searchable in English regardless of their original language.", "properties": { "mode": { "type": "string", "description": "Filter mode for original language selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of original languages to include or exclude based on the mode. Values are lowercase ISO 639-1 codes, for example `en`, `de` or `ja`, with `zh-Hans` and `zh-Hant` for Simplified and Traditional Chinese. Values are not validated against a fixed list, as new original languages are onboarded over time.", "items": { "type": "string" }, "example": ["de", "ja"] } }, "required": ["mode", "values"] }, "source": { "type": "object", "description": "Source filter to retrieve documents from specific sources.", "properties": { "mode": { "type": "string", "description": "Filter mode for source selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of source IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["ED68DC"] } }, "required": ["mode", "values"] }, "category": { "type": "object", "description": "Category filter to retrieve documents from specific categories. This enables selecting a related set of sources without having to add a long list of source IDs.", "properties": { "mode": { "type": "string", "description": "Filter mode for category selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of categories to include or exclude based on the mode.", "items": { "type": "string", "enum": ["expert_interviews", "filings", "my_files", "news", "news_premium", "news_public", "podcasts", "research", "research_academic_journals", "research_investment_research", "transcripts"] } } }, "required": ["mode", "values"] }, "tier": { "type": "object", "description": "Content tier filter to retrieve documents from specific content tiers. Tiers are how content is packaged and priced under the token-based consumption model.", "properties": { "mode": { "type": "string", "description": "Filter mode for content tier selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of content tiers to include or exclude based on the mode.", "items": { "type": "string", "enum": [ "corporate-communications", "premium-news", "expert-interviews", "earnings-transcripts", "regulatory-filings", "podcasts", "web", "private-data" ] } } }, "required": ["mode", "values"] }, "keyword": { "type": "object", "description": "Keyword filter to retrieve chunks based on keyword presence.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for keywords: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of keywords that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of keywords where at least one must be present in the chunk.", "items": { "type": "string" }, "example": [] }, "none_of": { "type": "array", "description": "Array of keywords that must not be present in the chunk.", "items": { "type": "string" }, "example": ["operating"] } }, "required": ["all_of", "any_of", "none_of"] }, "entity": { "type": "object", "description": "Entity filter to retrieve chunks where entities were identified.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for entities: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of entity IDs that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of entity IDs where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["228D42"] }, "none_of": { "type": "array", "description": "Array of entity IDs that must not be present in the document.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sentiment": { "type": "object", "description": "Sentiment filter to retrieve chunks based on sentiment score. All chunks contain a sentiment score ranging from -1.00 to 1.00, indicating how that chunk might impact the market and whether it will have a positive or negative effect.", "properties": { "ranges": { "type": "array", "description": "Array of sentiment score ranges to filter by. Each range specifies a minimum and maximum sentiment score.", "items": { "type": "object", "properties": { "min": { "type": "number", "format": "float", "description": "Minimum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -1.0 }, "max": { "type": "number", "format": "float", "description": "Maximum sentiment score for this range.", "minimum": -1.0, "maximum": 1.0, "example": -0.3 } }, "required": ["min", "max"] }, "example": [ { "min": -1.0, "max": -0.3 }, { "min": 0.3, "max": 1.0 } ] }, "values": { "type": "array", "description": "Array of sentiment categories to filter by. **Sunsetting**: Use `ranges` instead for more precise sentiment filtering.", "deprecated": true, "items": { "type": "string", "enum": ["positive", "negative", "neutral"], "description": "Sentiment categories: 'positive' (0.1 to 1.0), 'negative' (-0.1 to -1.0), 'neutral' (-0.1 to 0.1)" } } } }, "reporting_entities": { "type": "array", "description": "Select one or multiple companies for which the returned documents must have been reported by.", "items": { "type": "string" }, "example": ["228D42"] }, "reporting_periods": { "type": "array", "description": "Specify one or multiple combinations of a year and a quarter (e.g., Q1 2024, Q4 2023).", "items": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "description": "Fiscal year", "example": 2024 }, "fiscal_quarter": { "type": "integer", "description": "Fiscal quarter (1-4)", "minimum": 1, "maximum": 4, "example": 3 } }, "required": ["fiscal_year", "fiscal_quarter"] }, "example": [ { "fiscal_year": 2024, "fiscal_quarter": 3 } ] }, "topic": { "type": "object", "description": "Topic filter to retrieve chunks based on topic presence. Example: {\"any_of\": [\"business,stock-prices,stock-price-volatility,down,\"]} to find documents about stock price volatility.", "properties": { "search_in": { "type": "string", "enum": ["HEADLINE", "BODY", "ALL"], "description": "Specifies where to search for topics: HEADLINE (only in headlines), BODY (only in body text), or ALL (both). Defaults to ALL if not provided." }, "all_of": { "type": "array", "description": "Array of topics that must all be present in the chunk.", "items": { "type": "string" }, "example": [] }, "any_of": { "type": "array", "description": "Array of topics where at least one must be present in the chunk.", "items": { "type": "string" }, "example": ["business,stock-prices,stock-price-volatility,down,"] }, "none_of": { "type": "array", "description": "Array of topics that must not be present in the chunk.", "items": { "type": "string" }, "example": [] } }, "required": ["all_of", "any_of", "none_of"] }, "sections": { "type": "object", "description": "Section filter to restrict transcript and expert interview results to specific sections.", "properties": { "any_of": { "type": "array", "description": "Array of transcript sections where at least one must be present. Values are case-insensitive.", "items": { "type": "string", "enum": [ "MANAGEMENT-DISCUSSION", "QUESTION-ANSWER" ] }, "example": ["QUESTION-ANSWER"] } }, "required": ["any_of"] }, "tag": { "type": "object", "description": "Tag filter to retrieve documents from uploaded files that have been tagged with specific tags.", "properties": { "any_of": { "type": "array", "description": "Array of tags where at least one must be present in the uploaded file.", "items": { "type": "string" }, "example": ["research-report", "any-tag"] } }, "required": ["any_of"] }, "document": { "type": "object", "description": "Document filter to restrict the search to a list of specified documents. Use document IDs (e.g., from a previous search response) to search only within those documents.", "properties": { "mode": { "type": "string", "description": "Filter mode for document selection.", "enum": ["INCLUDE", "EXCLUDE"] }, "values": { "type": "array", "description": "Array of document IDs to include or exclude based on the mode.", "items": { "type": "string" }, "example": ["3C54E042B2B19B244F57D3C6415439D1"] } }, "required": ["mode", "values"] }, "chunk": { "type": "object", "description": "Chunk filter to narrow the search to a particular section within the document. Use when expanding the context of a previously retrieved chunk (e.g., from the 3rd chunk to the 7th). Useful to expand context around a chunk that was previously retrieved. Chunk indices are 1-based.", "properties": { "from": { "type": "integer", "description": "1-based index of the first chunk to include in the search range.", "example": 3 }, "to": { "type": "integer", "description": "1-based index of the last chunk to include in the search range (inclusive).", "example": 7 } }, "required": ["from", "to"] } } }, "auto_enrich_filters": { "type": "boolean", "description": "Advanced parameter that controls automatic enrichment of filters using the query text. When set to true (default), the system automatically extracts and adds relevant filter values from the query text. Set to false when you have created a strict query with specific keywords and entity filters and you do not want any extra values added to those filters." } } }, "limit": { "type": "integer", "description": "Maximum number of topics to retrieve. It must be lower than or equal to 1000.", "example": 1000 } }, "required": ["query"], "example": { "query": { "text": "Type a theme to get connected topics..." } } } } } }, "responses": { "200": { "description": "Topics co-mentions results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "object", "description": "Object containing array of topics that are co-mentioned with the search query.", "properties": { "topics": { "type": "array", "description": "Array of topics co-mentioned with the search query.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique topic identifier.", "example": "economy,taxes,import-tax,," }, "total_chunks_count": { "type": "integer", "description": "Total number of chunks where this topic appears.", "example": 2787 }, "total_headlines_count": { "type": "integer", "description": "Total number of titles where this topic appears.", "example": 384 } }, "required": ["id", "total_chunks_count", "total_headlines_count"] } } }, "required": ["topics"] }, "metadata": { "type": "object", "description": "Request metadata and timing information.", "properties": { "request_id": { "type": "string", "description": "Unique identifier for the request.", "example": "0d353dca-fc68-41ff-9f40-c27206f1650d" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the response was generated.", "example": "2025-10-02T15:24:34.017171+00:00" } }, "required": ["request_id", "timestamp"] }, "usage": { "$ref": "#/components/schemas/AggregateSearchUsage" } }, "required": ["results", "usage"] } } } } } } }, "/v1/documents/{document_id}": { "get": { "tags": ["Search"], "summary": "Fetch document", "operationId": "get_document", "description": "Returns a time-limited pre-signed URL for downloading the document in annotated (structured) JSON format. Issuing a GET request to that URL returns the document's content, metadata, and annotations. The URL expires after 24 hours; request a new one when it does.\n\nThis endpoint works for any document in Bigdata, whether it originates from the RavenPack catalog or from your own processed files.\n\nWhen `web_content` is `true`, the returned document also includes a direct URL to the publisher's original article on the web.", "parameters": [ { "name": "document_id", "in": "path", "required": true, "description": "The unique 32-character MD5 hex identifier for the document (e.g., `776769957735667D2F01F695EF4F1231`).", "schema": { "type": "string", "pattern": "^[A-F0-9]{32}$", "example": "776769957735667D2F01F695EF4F1231" } } ], "responses": { "200": { "description": "An object with a url and a web_content field is returned. When web_content is true, the returned document contains a direct link to the original web page in addition to the full analytics.", "content": { "application/json": { "schema": { "type": "object", "properties": { "web_content": { "type": "boolean", "description": "true when is a public URL.", "example": false }, "url": { "type": "string", "format": "uri", "description": "When you access the URL, you receive the complete document in JSON format with the structure: document (metadata), content (title and body blocks) and analytics (document-level metrics, events array, entities array). In the case of transcript-style documents, the document metadata includes normalized event context (participants, reporting fields, timestamps_utc). This is available for **Factset** documents, other providers like **Quartr** or **Third Bridge** will be available soon.", "example": "https://documents.bigdata.com/documents/776769957735667D2F01F695EF4F1231?signature=abc123..." }, "document": { "description": "**Returned by URL** - Document metadata including source information, timestamps, and details.", "allOf": [{ "$ref": "#/components/schemas/Document" }] }, "content": { "description": "**Returned by URL** - Document content including title, body blocks, entities, and sentences.", "allOf": [{ "$ref": "#/components/schemas/Content" }] }, "analytics": { "description": "**Returned by URL** - Document-level analytics, events array, and entities array.", "allOf": [{ "$ref": "#/components/schemas/FetchDocumentAnalytics" }] }, "software_versions": { "description": "**Returned by URL** - Optional pipeline build stamps when present.", "allOf": [{ "$ref": "#/components/schemas/SoftwareVersions" }] } }, "required": ["url"] }, "examples": { "response": { "summary": "API Response", "description": "The endpoint returns a pre-signed URL to download the document.", "value": { "url": "https://documents.bigdata.com/documents/776769957735667D2F01F695EF4F1231?signature=abc123...", "web_content": false } }, "document_from_url": { "summary": "Document (returned by URL)", "description": "When you access the URL (when web_content is false), you receive the complete document in JSON format: document metadata, content (title and body blocks) and analytics (document-level metrics, events array, entities array). Same structure as Get Annotated Document; see that endpoint for the full example including TABLE, LIST_ORDERED, LIST_UNORDERED body types and analytics.\n\nTranscript-class documents add normalized event context in metadata, such as participants, reporting dates, reporting entities and timestamps_utc. This is available for **Factset** documents, other providers like **Quartr** or **Third Bridge** will be available soon.", "value": { "document": { "rp_document_id": "679A67575E6C04213FB93D29E6AD91BE", "source": { "rp_external_source_id": "836C09E6173AAA3DA6A1415030B4EC2D", "rp_provider_id": "FSTR", "rp_source_id": "D4B903", "name": "Source Name", "rank": 1, "rp_channel_id": 350 }, "timestamps_utc": { "published": "2026-05-13 18:22:10.000", "reception": "2026-05-13 19:05:02.146", "analytics": "2026-05-13 19:12:35.698", "revision": "2026-05-13 19:12:35.698" }, "metadata": { "provider_document_id": "8821103:CorrectedTranscript:1002003", "revision": { "chain_id": "8821103" }, "transcript_event_date": "2026-05-13", "transcript_event_datetime": "2026-05-13 21:00:00", "transcript_event_type": "EC", "transcript_participants": { "0": { "id": "0", "value": "Speaker 1 (executive)", "type": "corprep", "title": "Chairman & Chief Executive Officer", "entity": "0D3E4F-E", "affiliation": "Example Sensor Corp.", "affiliation_entity": "0G5H6J-E", "rp_company_id": "4ABF38", "rp_person_id": "D3ROD1" }, "1": { "id": "1", "value": "Speaker 2 (executive)", "type": "corprep", "title": "Chief Financial Officer", "entity": "0K7L8M-E", "affiliation": "Example Sensor Corp.", "affiliation_entity": "0G5H6J-E", "rp_company_id": "4ABF38", "rp_person_id": "NSTS71" }, "2": { "id": "2", "value": "Speaker 3 (analyst)", "type": "analyst", "title": "Analyst", "entity": "0N9P0Q-E", "affiliation": "Example Global Partners LLC", "affiliation_entity": "0R1S2T-E", "rp_company_id": "HY0PTX", "rp_person_id": "9XQGTC" }, "3": { "id": "3", "value": "Speaker 4 (analyst)", "type": "analyst", "title": "Analyst", "entity": "0U3V4W-E", "affiliation": "Example Markets Inc.", "affiliation_entity": "0X5Y6Z-E", "rp_person_id": "4MJHX0" }, "4": { "id": "4", "value": "Speaker 5 (analyst)", "type": "analyst", "title": "Analyst", "entity": "0A7B8C-E", "affiliation": "Example Research Group LLC", "affiliation_entity": "0D9E0F-E", "rp_company_id": "DEC521", "rp_person_id": "KDO4MW" } } } }, "software_versions": { "collection_build": "0", "classification_build": "707", "metadata_build": "20260513" }, "content": { "stats": { "word_count": 8481, "byte_count": 1336670 }, "title": { "text": "Example Sensor Corp.: Q1 Earnings Call on May 13, 2026 - Transcript", "sentences": [ { "start": 0, "end": 67, "sentiment": "0.00", "sentiment_confidence": "1.00" } ], "entities": [ { "rp_entity_id": "4ABF38", "start": 0, "end": 20 }, { "rp_entity_id": "5AF7E2", "start": 25, "end": 33 }, { "rp_entity_id": "3DA2FA", "start": 42, "end": 54 } ], "events": [ { "event_similarity_key": "A1795745A27ECCF46AC3FA2708032A95", "start": 0, "end": 54 } ] }, "body": [ { "type": "TEXT", "text": "Ladies and gentlemen, good day, and welcome to Example Sensor Corp. Q1 FY twenty-six earnings conference call. As a reminder, all participant lines will be in listen-only mode until the Q&A portion.", "normalized_coordinates": [], "sentences": [ { "start": 0, "end": 100, "sentiment": "0.00", "sentiment_confidence": "1.00" }, { "start": 100, "end": 198, "sentiment": "0.15", "sentiment_confidence": "0.73" } ], "entities": [ { "rp_entity_id": "5AF7E2", "start": 47, "end": 67 }, { "rp_entity_id": "C408BB", "start": 22, "end": 30 }, { "rp_entity_id": "308257", "start": 186, "end": 189 } ] } ] }, "analytics": { "document": { "analytics_version": "2.0", "analytics_revision_number": 0, "document_type": "TRANSCRIPT-RAW", "document_record_count": 257, "title_similarity_key": "0A4AD1E8BF251E1A90E3B2376E471E07", "document_sentiment": 0.21, "document_sentiment_confidence": 0.65, "composite_sentiment_score": 0.04, "sentiment_impact_projection": -0.2, "stock_tone_sentiment": 0, "earnings_tone_sentiment": 0, "commentary_sentiment": 1, "mergers_acquisitions_sentiment": 0, "corporate_actions_sentiment": 0, "earnings_release_sentiment": 0, "product_key": "EDGE", "realtime": "Y" }, "events": [ { "event_similarity_key": "E7913FBE641945AC0670EEF684B6D8E0", "topic": "business", "group": "products-services", "type": "business-contract", "event_relevance": 77, "roles": [ { "rp_entity_id": "DD3BB1", "category": "business-contract", "fact_level": "fact", "document_record_index": 6, "match_type": "TEMPLATE", "event_sentiment": 0.49, "event_risk": 0.24, "sustainability_sentiment": 0.24, "credit_sentiment": 0.25, "interest_rate_sentiment": 0, "event_detection_distance": 0, "event_text": "Example Sensor Corp.: we entered into new contracts", "rp_event_detected_entity_id": "DD3BB1", "event_detected_entity_name": "Example Sensor Corp." } ] } ], "entities": [ { "rp_entity_id": "4A6F00", "entity_type": "COMP", "entity_name": "Example Listed Corp.", "country_code": "US", "document_record_index": 217, "entity_hierarchy_level": 1, "entity_detection_type": "direct", "entity_detection_distance": 0, "entity_relevance": 26, "entity_sentiment": 0.25, "entity_sentiment_confidence": 0.05, "entity_text_sentiment": 0.25, "entity_text_sent_confidence": 0.05, "analyst_ratings_sentiment": 0, "multi_stock_sentiment": 0 } ] } } } } } } }, "400": { "description": "Invalid document_id" }, "403": { "description": "Access to document denied" }, "404": { "description": "Document not found." } } } } } }