{ "openapi": "3.0.1", "info": { "title": "Telegram Keyword Search & Alerts Scraper", "description": "Unofficial public-source Telegram scraper. Search posts by keyword, monitor known public channels, receive only new matches, cluster reposts, and export structured Telegram data. No Telegram account required; optional AI relevance.", "version": "0.1", "x-build-id": "aP69jE3DX2FWyyPAg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/i-scraper~telegram-keyword-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-i-scraper-telegram-keyword-search", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/i-scraper~telegram-keyword-search/runs": { "post": { "operationId": "runs-sync-i-scraper-telegram-keyword-search", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/i-scraper~telegram-keyword-search/run-sync": { "post": { "operationId": "run-sync-i-scraper-telegram-keyword-search", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "queries": { "title": "Search queries", "maxItems": 20, "type": "array", "description": "Keywords and matching rules. Provide at least one query, an intent, or a known channel.", "items": { "type": "object", "additionalProperties": false, "properties": { "text": { "title": "Query text", "description": "Phrase, words, or a regular expression to match.", "type": "string", "editor": "textfield", "minLength": 1, "maxLength": 300 }, "mode": { "title": "Match mode", "description": "Exact phrase, all words, any word, regex, or semantic intent.", "type": "string", "editor": "select", "enum": [ "exact", "allWords", "anyWords", "regex", "semanticIntent" ], "enumTitles": [ "Exact phrase", "All words", "Any word", "Regular expression", "Semantic intent" ], "default": "exact" }, "includeTerms": { "title": "Required terms", "description": "Every listed term must occur in a matching message.", "type": "array", "editor": "stringList", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "excludeTerms": { "title": "Excluded terms", "description": "Messages containing any listed term are excluded.", "type": "array", "editor": "stringList", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "synonyms": { "title": "Synonyms and spelling variants", "description": "Optional additional phrases mapped to this query.", "type": "array", "editor": "stringList", "maxItems": 10, "items": { "type": "string", "maxLength": 100 } }, "transliterate": { "title": "Add transliteration", "description": "Generate a Latin transliteration variant for Cyrillic text.", "type": "boolean", "editor": "checkbox", "default": true } }, "required": [ "text" ] }, "default": [ { "text": "artificial intelligence", "mode": "allWords", "excludeTerms": [] } ] }, "intent": { "title": "Monitoring intent", "maxLength": 2000, "type": "string", "description": "Natural-language description of the signal you want. It is also used for AI relevance when AI mode is enabled." }, "knownChannels": { "title": "Channels to search", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Public channel usernames or t.me links. When provided, results are limited to these channels unless global web search is explicitly enabled below.", "items": { "type": "string", "maxLength": 200 }, "default": [] }, "searchGlobalWeb": { "title": "Also search all public Telegram sources", "type": "boolean", "description": "When channels are provided above, also run global public web discovery. Leave disabled to return results only from the specified channels. Global search runs automatically when no channels are provided.", "default": false }, "includeChannels": { "title": "Only these channels", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Optional allowlist of public channel usernames or t.me links.", "items": { "type": "string", "maxLength": 200 }, "default": [] }, "excludeChannels": { "title": "Exclude channels", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Public channel usernames or t.me links to ignore.", "items": { "type": "string", "maxLength": 200 }, "default": [] }, "fromDate": { "title": "Published from", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "type": "string", "description": "Only return messages published on or after this UTC date." }, "toDate": { "title": "Published to", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "type": "string", "description": "Only return messages published on or before this UTC date." }, "languages": { "title": "Languages", "maxItems": 20, "uniqueItems": true, "type": "array", "description": "Optional ISO 639-1 language codes such as en, es, or ru.", "items": { "type": "string", "pattern": "^[a-zA-Z]{2,3}$" }, "default": [] }, "minViews": { "title": "Minimum views", "minimum": 0, "type": "integer", "description": "Skip messages with a known view count below this value. Messages without a view count remain eligible." }, "minReactions": { "title": "Minimum reactions", "minimum": 0, "type": "integer", "description": "Skip messages with a known reaction count below this value. Messages without reaction data remain eligible." }, "maxResultsPerQuery": { "title": "Maximum results per query", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum deterministic matches retained for each original query.", "default": 100 }, "onlyNew": { "title": "Return only new messages", "type": "boolean", "description": "Skip messages delivered by previous runs with the same monitor ID.", "default": false }, "monitorId": { "title": "Monitor ID", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$", "type": "string", "description": "Stable identifier used for persistent checkpoints. Required when only-new mode is enabled." }, "webSearchProvider": { "title": "Public web discovery provider", "enum": [ "auto", "duckduckgo", "bing" ], "type": "string", "description": "Auto tries bounded public search providers in order and reports partial failures transparently.", "default": "auto" }, "expandQueriesWithAi": { "title": "Expand queries with AI", "type": "boolean", "description": "Generate a small bounded set of intent-preserving retrieval variants. Requires OpenAI mode and an API key.", "default": false }, "aiMode": { "title": "AI enrichment", "enum": [ "off", "openai" ], "type": "string", "description": "Off preserves raw deterministic results. OpenAI adds relevance evidence within the configured item and dollar budgets.", "default": "off" }, "openaiApiKey": { "title": "OpenAI API key", "type": "string", "description": "Optional encrypted API key used only when OpenAI enrichment is enabled. The OPENAI_API_KEY environment variable is also supported." }, "openaiModel": { "title": "OpenAI model", "maxLength": 100, "type": "string", "description": "Model used for structured relevance and optional expansion.", "default": "gpt-4.1-mini" }, "relevanceThreshold": { "title": "AI relevance threshold", "minimum": 0, "maximum": 100, "type": "integer", "description": "Minimum AI relevance score retained in relevant-only alert mode.", "default": 70 }, "clusterResults": { "title": "Cluster reposts and related messages", "type": "boolean", "description": "Group exact and near-duplicate messages while preserving every source link.", "default": true }, "generateDigest": { "title": "Generate digest", "type": "boolean", "description": "Emit a compact run digest based on the resulting clusters.", "default": false }, "maxAiItems": { "title": "Maximum AI items", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Hard cap on messages sent for AI classification.", "default": 200 }, "aiBudgetUsd": { "title": "Maximum estimated AI spend", "minimum": 0, "maximum": 100, "type": "number", "description": "Conservative run budget. Enrichment stops before this estimate is exceeded and raw results are preserved.", "default": 1 }, "alertMode": { "title": "Alert mode", "enum": [ "allMatches", "relevantOnly" ], "type": "string", "description": "Return all deterministic matches or only AI-relevant matches when AI is enabled.", "default": "relevantOnly" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional proxy for public web and Telegram preview requests.", "default": { "useApifyProxy": false } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }