{ "openapi": "3.0.1", "info": { "title": "Brand Mentions Monitor — Web Mentions & Sentiment", "description": "Track brand mentions on news, blogs, forums & shops with sentiment, emotions, domain rank & monthly trend. Only-new mode for schedules.", "version": "1.0", "x-build-id": "zJz9UkTbILgzDoIbo" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cheapapi~brand-mentions-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cheapapi-brand-mentions-monitor", "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/cheapapi~brand-mentions-monitor/runs": { "post": { "operationId": "runs-sync-cheapapi-brand-mentions-monitor", "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/cheapapi~brand-mentions-monitor/run-sync": { "post": { "operationId": "run-sync-cheapapi-brand-mentions-monitor", "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", "required": [ "keywords" ], "properties": { "keywords": { "title": "Brands or keywords", "type": "array", "description": "Brand names, product names or phrases to monitor, one per line (up to 50). Phrases with spaces are matched exactly (turn off \"Exact phrase\" below to match the words anywhere). Matching is case-insensitive. A keyword whose search delivers no mention (nothing matches, or nothing new) is charged one \"Search without delivered mentions\" ($0.0303), because the search is paid for either way.", "items": { "type": "string" } }, "maxMentions": { "title": "Max mentions per keyword", "minimum": 1, "maximum": 20000, "type": "integer", "description": "How many mentions to deliver per keyword (1–20,000). Each 1,000 mentions are one search.", "default": 100 }, "dateFrom": { "title": "From date (optional)", "type": "string", "description": "Only mentions published on or after this date. Use 2025-01-31 or a relative period like \"30 days\", \"6 months\" or \"1 year\". Pages without a known publication date are left out when a date range is set (see \"Date range applies to\")." }, "dateTo": { "title": "To date (optional)", "type": "string", "description": "Only mentions published on or before this date (inclusive). Same formats as \"From date\"." }, "languages": { "title": "Languages (optional)", "type": "array", "description": "Only mentions written in these languages, as ISO codes (en, de, es, fr, tr, …). Empty = all languages.", "items": { "type": "string" } }, "countries": { "title": "Countries (optional)", "type": "array", "description": "Only mentions from websites in these countries, as ISO codes (US, GB, DE, TR, …) or English names. Empty = all countries.", "items": { "type": "string" } }, "onlyNewMentions": { "title": "Only new mentions (for scheduled monitoring)", "type": "boolean", "description": "Remember what was already delivered and return only mentions that are new since the previous run with the same keyword and filters. The first run returns everything (up to the maximum). Repeats are never charged as mentions, but each search is paid for: a run where nothing is new costs $0.0303 per keyword (\"Search without delivered mentions\"), and every returned mention that is skipped as already delivered costs $0.0001 (\"Fetched mention not delivered\").", "default": false }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "Match multi-word keywords as an exact phrase (\"apple watch\"). Turn off to find pages with the words in any order. You can also put your own quotes around a keyword.", "default": true }, "matchInFields": { "title": "Match only in", "type": "array", "description": "Require the keyword in specific parts of the page. Empty = anywhere in the indexed text.", "items": { "type": "string", "enum": [ "snippet", "title", "main_title", "previous_title" ], "enumTitles": [ "Text snippet", "Section title (heading above the text)", "Page title", "Previous section title" ] } }, "pageTypes": { "title": "Page types", "type": "array", "description": "Only these kinds of websites. Empty = all.", "items": { "type": "string", "enum": [ "news", "blogs", "message-boards", "ecommerce", "organization" ], "enumTitles": [ "News", "Blogs", "Forums & message boards", "Online shops", "Organizations" ] } }, "searchMode": { "title": "Results per domain", "enum": [ "all", "onePerDomain" ], "type": "string", "description": "\"All mentions\" returns every matching text block. \"One per domain\" returns only the best mention from each website — useful to see how many different sites talk about you.", "default": "all" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "newest", "oldest", "recentlyDiscovered", "mostPositive", "mostNegative", "highestDomainRank", "highestPageRank", "highestQuality" ], "type": "string", "description": "Order of the results. With \"Only new mentions\" the default is \"Recently discovered\"." }, "dateField": { "title": "Date range applies to", "enum": [ "published", "discovered" ], "type": "string", "description": "\"Publication date\" uses the date the page was published (pages without a known date are excluded). \"Discovery date\" uses when the page was found by our crawler — every page has one.", "default": "published" }, "includeDomains": { "title": "Only these domains", "type": "array", "description": "Only mentions on these websites (e.g. reddit.com, nytimes.com). Subdomains are included.", "items": { "type": "string" } }, "excludeDomains": { "title": "Exclude domains", "type": "array", "description": "Skip mentions on these websites, e.g. your own site.", "items": { "type": "string" } }, "rankScale": { "title": "Rank scale", "enum": [ "0-100", "0-1000" ], "type": "string", "description": "Scale for domain rank and page rank, in the output and in the rank filters below.", "default": "0-100" }, "minDomainRank": { "title": "Min domain rank", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Only websites with at least this authority (on the rank scale above)." }, "maxDomainRank": { "title": "Max domain rank", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Only websites with at most this authority." }, "minPageRank": { "title": "Min page rank", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Only pages with at least this authority (on the rank scale above)." }, "maxPageRank": { "title": "Max page rank", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Only pages with at most this authority." }, "maxSpamScore": { "title": "Max spam score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Skip websites with a higher spam score (0–100). Try 30 to remove most low-quality sites." }, "minContentQuality": { "title": "Min content quality", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only text blocks with at least this content quality score (0–100)." }, "sentiment": { "title": "Sentiment", "enum": [ "any", "positive", "negative", "neutral" ], "type": "string", "description": "Only mentions with this sentiment (probability at least \"Minimum sentiment probability\").", "default": "any" }, "sentimentMinScore": { "title": "Minimum sentiment probability", "minimum": 0, "maximum": 1, "type": "number", "description": "0–1, used with \"Sentiment\". A mention counts as positive/negative/neutral when that probability is at least this value. Default 0.4.", "default": 0.4 }, "emotion": { "title": "Emotion", "enum": [ "any", "anger", "happiness", "love", "sadness", "share", "fun" ], "type": "string", "description": "Only mentions expressing this emotion (probability at least \"Minimum emotion probability\").", "default": "any" }, "emotionMinScore": { "title": "Minimum emotion probability", "minimum": 0, "maximum": 1, "type": "number", "description": "0–1, used with \"Emotion\". A mention counts toward the emotion when that probability is at least this value. Default 0.4.", "default": 0.4 }, "monitorId": { "title": "Monitor name", "type": "string", "description": "Optional name for the \"Only new mentions\" memory (e.g. \"acme-weekly\"). Runs with the same name share one memory per keyword, even if you change filters. Empty = one memory per keyword + filter combination." }, "resetMonitor": { "title": "Start the memory over", "type": "boolean", "description": "Forget previously delivered mentions for this run's keywords and treat everything as new.", "default": false }, "webWideStats": { "title": "Add web-wide statistics (paid add-on)", "type": "boolean", "description": "Adds to each keyword's summary: the total number of matching mentions on the whole web with sentiment and emotion counts, top domains, countries, languages, categories and a trend over time — not just for the mentions you downloaded. $0.08 once per keyword when data is returned; $0.0786 when the lookup was made but returned no data (skipped for free when the mentions search already found no matching page). The free summary of delivered mentions is always included.", "default": false }, "trendGrouping": { "title": "Trend grouping", "enum": [ "month", "week", "day" ], "type": "string", "description": "Time buckets of the web-wide trend. The trend covers the date range above, or the last 12 months (max 400 buckets).", "default": "month" }, "topListSize": { "title": "Top list size", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many top domains, categories, countries etc. the web-wide statistics list (1–20). Also the length of the top-domain list in the free summary.", "default": 10 }, "positiveThreshold": { "title": "Sentiment threshold", "minimum": 0, "maximum": 1, "type": "number", "description": "0–1. Minimum probability for a mention to count as positive/negative/neutral in the web-wide statistics. Default 0.4.", "default": 0.4 }, "emotionThreshold": { "title": "Emotion threshold", "minimum": 0, "maximum": 1, "type": "number", "description": "0–1. Minimum probability for a mention to count toward an emotion in the web-wide statistics. Default 0.4.", "default": 0.4 }, "customFilters": { "title": "Custom filters (JSON)", "type": "array", "description": "Expert filter expression added to the filters above with AND. Format: [field, operator, value] or [[…], \"and\"/\"or\", […]]. Fields: url, domain, main_domain, country, language, url_rank, spam_score, domain_rank, score, fetch_time, page_types, page_category, content_info.title, content_info.main_title, content_info.snippet, content_info.author, content_info.content_type, content_info.date_published, content_info.content_quality_score, content_info.level, content_info.text_category, content_info.connotation_types.positive|negative|neutral, content_info.sentiment_connotations.anger|happiness|love|sadness|share|fun. Operators: =, <>, <, <=, >, >=, in, not_in, like, not_like, regex, not_regex, match, not_match, has, has_not. Dates look like \"2025-01-31 00:00:00 +00:00\". Max 8 conditions in total." }, "customSort": { "title": "Custom sort", "type": "array", "description": "Up to 3 sort rules like \"domain_rank,desc\" or \"content_info.date_published,desc\". Overrides \"Sort by\".", "items": { "type": "string" } } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }