{ "openapi": "3.0.1", "info": { "title": "Social Listening Mentions API - Sentiment, Topics, Brandwatch", "description": "Export social listening data from your own Brandwatch Consumer Research account: mentions with sentiment, author, reach and location, filtered by date, source, language and country, plus mention totals, volume and sentiment charts, topics, top authors and sites. Read only. Bring your own token.", "version": "0.1", "x-build-id": "uUqrI5aoEBrwhsalF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~social-listening-mentions-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-social-listening-mentions-api", "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/nabeelbaghoor~social-listening-mentions-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-social-listening-mentions-api", "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/nabeelbaghoor~social-listening-mentions-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-social-listening-mentions-api", "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": { "mode": { "title": "What to read", "enum": [ "projects", "queries", "queryGroups", "mentions", "mentionCount", "chart", "topics", "topAuthors", "topSites", "locations" ], "type": "string", "description": "Projects lists every project your API user can open and needs nothing else, so it is the default. Queries and query groups list what is inside one project. Mentions, total mentions, chart data, topics, top authors and top sites read the data of saved queries or query groups and need the project ID plus at least one query or query group ID. Location lookup finds the IDs the location filter takes.", "default": "projects" }, "projectId": { "title": "Project ID", "type": "string", "description": "The numeric project ID, as the projects mode lists it. Needed by every mode except projects and location lookup." }, "queryIds": { "title": "Query IDs", "type": "array", "description": "Numeric IDs of the saved queries or channels to read, as the queries mode lists them. Data modes need at least one query ID or query group ID.", "items": { "type": "string" } }, "queryGroupIds": { "title": "Query group IDs", "type": "array", "description": "Numeric IDs of query groups to read, as the query groups mode lists them. Can be combined with query IDs.", "items": { "type": "string" } }, "startDate": { "title": "Start date", "type": "string", "description": "Data modes. The start of the range, as YYYY-MM-DD or a timestamp such as 2026-09-01T00:00:00-0500. Defaults to 30 days before the end date." }, "endDate": { "title": "End date", "type": "string", "description": "Data modes. The end of the range (exclusive), as YYYY-MM-DD or a timestamp. Defaults to tomorrow, so today is included." }, "sentiment": { "title": "Sentiment", "type": "array", "description": "Data modes. Keep only mentions with these sentiments. Leave empty for all.", "items": { "type": "string", "enum": [ "positive", "neutral", "negative" ], "enumTitles": [ "Positive", "Neutral", "Negative" ] } }, "pageTypes": { "title": "Page types (sources)", "type": "array", "description": "Data modes. Keep only mentions from these content sources. Leave empty for every source the queries collect.", "items": { "type": "string", "enum": [ "twitter", "facebook", "instagram", "youtube", "tumblr", "news", "blog", "forum", "review", "lexis_nexis_licensed_news", "four_chan", "dark_web", "qq", "sina_weibo", "vk" ], "enumTitles": [ "X (Twitter)", "Facebook", "Instagram", "YouTube", "Tumblr", "News", "Blogs", "Forums", "Reviews", "LexisNexis licensed news", "4chan", "Dark web", "QQ", "Sina Weibo", "VK" ] } }, "languages": { "title": "Languages", "type": "array", "description": "Data modes. Keep only mentions in these languages. Leave empty for all.", "items": { "type": "string", "enum": [ "ab", "aa", "af", "ak", "sq", "am", "ar", "hy", "as", "ay", "az", "ba", "eu", "be", "bn", "bh", "bi", "bs", "br", "bg", "my", "ca", "ceb", "km", "chr", "ny", "zh", "zh-Hant", "co", "hr", "cs", "da", "dv", "nl", "dz", "en", "eo", "et", "ee", "fo", "fj", "fi", "fr", "gaa", "gd", "gl", "lg", "ka", "de", "el", "gn", "gu", "ht", "ha", "haw", "he", "hi", "hmn", "hu", "is", "ig", "id", "ia", "ie", "iu", "ik", "ga", "it", "ja", "jv", "kl", "kn", "pam", "ks", "kk", "kha", "rw", "ko", "kri", "ku", "ky", "lo", "la", "lv", "lif", "ln", "lt", "loz", "lua", "luo", "lb", "mk", "mg", "ms", "ml", "mt", "gv", "mi", "mr", "mfe", "mn", "sr-ME", "na", "ne", "new", "nso", "no", "nn", "oc", "or", "om", "os", "pa", "ps", "fa", "pl", "pt", "qu", "raj", "ro", "rm", "rn", "ru", "sm", "sg", "sa", "sco", "sr", "crs", "sn", "sd", "si", "sk", "sl", "so", "st", "nr", "es", "su", "sw", "ss", "sv", "syr", "tl", "tg", "ta", "tt", "te", "th", "bo", "ti", "to", "ts", "tn", "tum", "tr", "tk", "tw", "ug", "uk", "un", "ur", "uz", "ve", "vi", "vo", "war", "cy", "fy", "wo", "xh", "yi", "yo", "za", "zu" ], "enumTitles": [ "Abkhazian (ab)", "Afar (aa)", "Afrikaans (af)", "Akan (ak)", "Albanian (sq)", "Amharic (am)", "Arabic (ar)", "Armenian (hy)", "Assamese (as)", "Aymara (ay)", "Azerbaijani (az)", "Bashkir (ba)", "Basque (eu)", "Belarusian (be)", "Bengali (bn)", "Bihari languages (bh)", "Bislama (bi)", "Bosnian (bs)", "Breton (br)", "Bulgarian (bg)", "Burmese (my)", "Catalan (ca)", "Cebuano (ceb)", "Central Khmer (km)", "Cherokee (chr)", "Chewa (ny)", "Chinese (zh)", "Chinese Traditional (zh-Hant)", "Corsican (co)", "Croatian (hr)", "Czech (cs)", "Danish (da)", "Divehi (dv)", "Dutch (nl)", "Dzongkha (dz)", "English (en)", "Esperanto (eo)", "Estonian (et)", "Ewe (ee)", "Faroese (fo)", "Fijian (fj)", "Finnish (fi)", "French (fr)", "Ga (gaa)", "Gaelic (gd)", "Galician (gl)", "Ganda (lg)", "Georgian (ka)", "German (de)", "Greek (el)", "Guarani (gn)", "Gujarati (gu)", "Haitian (ht)", "Hausa (ha)", "Hawaiian (haw)", "Hebrew (he)", "Hindi (hi)", "Hmong (hmn)", "Hungarian (hu)", "Icelandic (is)", "Igbo (ig)", "Indonesian (id)", "Interlingua (ia)", "Interlingue, Occidental (ie)", "Inuktitut (iu)", "Inupiaq (ik)", "Irish (ga)", "Italian (it)", "Japanese (ja)", "Javanese (jv)", "Kalaallisut (kl)", "Kannada (kn)", "Kapampangan (pam)", "Kashmiri (ks)", "Kazakh (kk)", "Khasi (kha)", "Kinyarwanda (rw)", "Korean (ko)", "Krio (kri)", "Kurdish (ku)", "Kyrgyz (ky)", "Lao (lo)", "Latin (la)", "Latvian (lv)", "Limbu (lif)", "Lingala (ln)", "Lithuanian (lt)", "Lozi (loz)", "Luba-Kasai (lua)", "Luo (luo)", "Luxembourgish (lb)", "Macedonian (mk)", "Malagasy (mg)", "Malay (ms)", "Malayalam (ml)", "Maltese (mt)", "Manx (gv)", "Maori (mi)", "Marathi (mr)", "Mauritian (mfe)", "Mongolian (mn)", "Montenegrin (sr-ME)", "Nauru (na)", "Nepali (ne)", "Newar (new)", "Northern Sotho (nso)", "Norwegian (no)", "Norwegian Nynorsk (nn)", "Occitan (oc)", "Oriya (or)", "Oromo (om)", "Ossetic (os)", "Panjabi (pa)", "Pashto (ps)", "Persian (fa)", "Polish (pl)", "Portuguese (pt)", "Quechua (qu)", "Rajasthani (raj)", "Romanian (ro)", "Romansh (rm)", "Rundi (rn)", "Russian (ru)", "Samoan (sm)", "Sango (sg)", "Sanskrit (sa)", "Scots (sco)", "Serbian (sr)", "Seychellois (crs)", "Shona (sn)", "Sindhi (sd)", "Sinhala (si)", "Slovak (sk)", "Slovenian (sl)", "Somali (so)", "Southern Sotho (st)", "South Ndebele (nr)", "Spanish (es)", "Sundanese (su)", "Swahili (sw)", "Swati (ss)", "Swedish (sv)", "Syriac (syr)", "Tagalog (tl)", "Tajik (tg)", "Tamil (ta)", "Tatar (tt)", "Telugu (te)", "Thai (th)", "Tibetan (bo)", "Tigrinya (ti)", "Tonga (to)", "Tsonga (ts)", "Tswana (tn)", "Tumbuka (tum)", "Turkish (tr)", "Turkmen (tk)", "Twi (tw)", "Uighur (ug)", "Ukrainian (uk)", "Unknown (un)", "Urdu (ur)", "Uzbek (uz)", "Venda (ve)", "Vietnamese (vi)", "Volapük (vo)", "Waray (war)", "Welsh (cy)", "Western Frisian (fy)", "Wolof (wo)", "Xhosa (xh)", "Yiddish (yi)", "Yoruba (yo)", "Zhuang (za)", "Zulu (zu)" ] } }, "locations": { "title": "Locations (countries, regions, cities)", "type": "array", "description": "Data modes. Keep only mentions posted from these locations, given as location IDs. Find a country, region, city or continent ID with the location lookup mode, for example USA.OR for Oregon.", "items": { "type": "string" } }, "search": { "title": "Text search within mentions", "type": "string", "description": "Data modes. Keep only mentions that also match this search text." }, "domains": { "title": "Domains", "type": "array", "description": "Data modes. Keep only mentions from these site domains, such as reddit.com.", "items": { "type": "string" } }, "genders": { "title": "Author gender", "type": "array", "description": "Data modes. Keep only mentions whose author has this gender, where the provider knows it.", "items": { "type": "string", "enum": [ "female", "male" ], "enumTitles": [ "Female", "Male" ] } }, "accountTypes": { "title": "Author account type", "type": "array", "description": "Data modes. Keep only mentions from individual or organisational accounts.", "items": { "type": "string", "enum": [ "individual", "organisational" ], "enumTitles": [ "Individual", "Organisational" ] } }, "extraFilters": { "title": "Extra filters", "type": "object", "description": "Data modes. Any other documented filter as an object of filter name to value, or to a list of values for a filter that can repeat, for example {\"xdomain\": \"example.com\", \"impressionsMin\": 1000, \"tag\": [\"Complaint\"]}. Names outside the provider's Available Filters list are refused." }, "fullText": { "title": "Full text", "type": "boolean", "description": "Mentions mode. Read the full text of each mention instead of a snippet, where the source allows it. X posts, online news and LinkedIn content are restricted by the provider.", "default": false }, "orderBy": { "title": "Sort mentions by", "enum": [ "date", "added", "updated", "impact", "impressions", "reachestimate", "monthlyvisitors", "author", "title", "publicationname", "accounttype", "gender", "twitterfollowers", "twitterretweets", "twitterreplycount", "twitterLikeCount", "facebookcomments", "facebooklikes", "facebookshares", "instagramlikecount", "instagramcommentcount", "instagraminteractionscount", "linkedinEngagement", "linkedinImpressions", "priority", "status", "checked", "md5" ], "type": "string", "description": "Mentions mode. The field mentions are sorted by.", "default": "date" }, "orderDirection": { "title": "Sort direction", "enum": [ "desc", "asc" ], "type": "string", "description": "Mentions mode. Newest or largest first (desc), or the reverse (asc).", "default": "desc" }, "chartAggregate": { "title": "Chart measure", "enum": [ "volume", "authors", "domains", "impressions", "netSentiment", "reachEstimate", "twitterFollowers", "twitterLikeCount", "engagementScore" ], "type": "string", "description": "Chart data mode. What is added up in each cell of the chart.", "default": "volume" }, "chartDimension1": { "title": "Chart first breakdown", "enum": [ "queries", "queryGroups", "sentiment", "authors", "languages", "categories", "parentCategories", "mixedCategories", "tags", "assignment", "checked", "priority", "status", "continents", "countries", "regions", "cities", "months", "weeks", "days", "hours", "minutes", "hourOfDay", "dayOfWeek", "accountTypes", "gender", "interest", "profession", "pageTypes", "domains" ], "type": "string", "description": "Chart data mode. The first breakdown (one row group per value), such as queries, sentiment, pageTypes or countries.", "default": "queries" }, "chartDimension2": { "title": "Chart second breakdown", "enum": [ "queries", "queryGroups", "sentiment", "authors", "languages", "categories", "parentCategories", "mixedCategories", "tags", "assignment", "checked", "priority", "status", "continents", "countries", "regions", "cities", "months", "weeks", "days", "hours", "minutes", "hourOfDay", "dayOfWeek", "accountTypes", "gender", "interest", "profession", "pageTypes", "domains" ], "type": "string", "description": "Chart data mode. The second breakdown (one row per value within each group), such as days, weeks or months for a trend.", "default": "days" }, "timezone": { "title": "Time zone for chart and topic buckets", "type": "string", "description": "Chart data and topics modes. A time zone such as America/New_York, so days and weeks follow local time. It does not filter mentions." }, "topicsExtract": { "title": "Topic kind", "enum": [ "words", "phrases", "hashtags", "entities", "emojis", "people", "places", "organisations" ], "type": "string", "description": "Topics mode. What to extract from the mentions.", "default": "phrases" }, "topicsMetrics": { "title": "Topic metrics", "type": "array", "description": "Topics mode. Metrics to return with each topic. Fewer metrics answer faster. Defaults to volume, percentage volume, sentiment and trending.", "items": { "type": "string", "enum": [ "volume", "percentageVolume", "sentiment", "gender", "trending", "timeSeries" ] } }, "topicsOrderBy": { "title": "Topic order", "enum": [ "volume", "trending" ], "type": "string", "description": "Topics mode. Rank topics by volume or by how fast they are trending.", "default": "volume" }, "queryType": { "title": "Query type", "enum": [ "all", "monitor", "twitter", "publicfacebook", "instagram" ], "type": "string", "description": "Queries mode. List every query, or only boolean monitors or one kind of channel.", "default": "all" }, "locationType": { "title": "Location type", "enum": [ "country", "region", "city", "continent" ], "type": "string", "description": "Location lookup mode. The kind of location to search for.", "default": "country" }, "locationPrefix": { "title": "Location prefix", "type": "string", "description": "Location lookup mode. What the location name or ID begins with, such as \"united\" or \"usa\"." }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most rows this run returns. Mentions are read up to 5,000 per call; topics, top authors and top sites use it as their limit (top lists cap at 1,000).", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 60, "type": "integer", "description": "Pacing ceiling. The provider allows 30 calls per client in any 10 minutes by default, shared with every other tool on your account, so 3 per minute is the safe default. Raise it only if your account manager raised your limit.", "default": 3 }, "apiKey": { "title": "Access token", "type": "string", "description": "Your own Consumer Research API access token, as POST /oauth/token returns it to your API user. Stored as a secret. Can also be supplied as the DATA_API_KEY environment secret." } } }, "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 } } } } } } } } } }