{ "openapi": "3.0.1", "info": { "title": "Social Listening Analytics API - Mentions, Sentiment, Synthesio", "description": "Export social listening data from your own Synthesio account: mentions with sentiment, Synthesio rank, author, site, country and topics, filtered by query, dates, language, media and topic, plus analytics by any field, topic trees and projects. Read only. Bring your own token or API credentials.", "version": "0.1", "x-build-id": "4K6BM8uMdrTnh2bCj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~social-listening-analytics-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-social-listening-analytics-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-analytics-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-social-listening-analytics-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-analytics-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-social-listening-analytics-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", "mentions", "analytics", "topics", "account" ], "type": "string", "description": "Projects lists every project (dashboard) the user behind your credentials can open and needs nothing else, so it is the default. Mentions pages through one project's mentions with the filters below. Analytics counts mentions by a field (over time, by sentiment, language, country, site, topic, author demographics and more) or sums a metric such as influence. Topic tree reads the topics set up in one project. Account shows the user and token scope, which is a quick credentials check.", "default": "projects" }, "reportId": { "title": "Project ID", "type": "string", "description": "The numeric Synthesio project (dashboard, called report in the API) ID, as the projects mode lists it, such as 38298. Needed by mentions, analytics and topic tree. In the projects mode, a comma separated list keeps only those projects." }, "query": { "title": "Query", "type": "string", "description": "Mentions and analytics. Keep only mentions matching this query, in the same syntax as the Synthesio product, such as brand AND \"new york\". Highlighting uses it." }, "dateFilter": { "title": "Date filter applies to", "enum": [ "period", "infused_at", "crawled_at", "review_date" ], "type": "string", "description": "Mentions and analytics. Which date the start and end filter: the mention date (period), the date it was added to the project (infused_at, best for incremental exports), the date Synthesio crawled it, or the manual review date.", "default": "period" }, "dateFrom": { "title": "Date start", "type": "string", "description": "Mentions and analytics. YYYY-MM-DD (from midnight UTC) or an ISO 8601 date-time such as 2026-09-01T00:00:00Z." }, "dateTo": { "title": "Date end", "type": "string", "description": "Mentions and analytics. YYYY-MM-DD (to the end of that day UTC) or an ISO 8601 date-time." }, "sentiments": { "title": "Sentiments", "type": "array", "description": "Mentions and analytics. Keep only these sentiments.", "items": { "type": "string", "enum": [ "positive", "neutral", "negative", "undefined" ], "enumTitles": [ "Positive", "Neutral", "Negative", "Undefined" ] } }, "languages": { "title": "Languages", "type": "array", "description": "Mentions and analytics. ISO 639-3 codes such as eng, fra, spa, deu, or zho, zho-Hans and zho-Hant for all Chinese.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Mentions and analytics. ISO 3166-1 alpha-3 codes such as USA, FRA, GBR.", "items": { "type": "string" } }, "topicIds": { "title": "Topic IDs", "type": "array", "description": "Mentions and analytics. Keep only mentions matching any of these topics, as the topic tree mode lists them.", "items": { "type": "string" } }, "mediaGroups": { "title": "Media groups", "type": "array", "description": "Mentions and analytics. Social media, mainstream media, or both.", "items": { "type": "string", "enum": [ "social", "mainstream" ], "enumTitles": [ "Social", "Mainstream" ] } }, "siteTypes": { "title": "Site types", "type": "array", "description": "Mentions and analytics. Keep only these documented site categories.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "7", "8", "9", "10", "11", "13", "14", "15", "16", "17", "20", "21" ], "enumTitles": [ "National newspaper", "Regional newspaper", "Institution, government", "Professional news, industry news", "Company", "General news, magazine", "News agency", "Blog", "TV, radio", "Forum", "X (Twitter)", "Video and photo sharing", "Consumer opinions", "Comments", "Social network", "Facebook community app", "Hosted community" ] } }, "siteIds": { "title": "Site IDs", "type": "array", "description": "Mentions and analytics. Numeric Synthesio site IDs: 9938 X (Twitter), 1650630 Instagram, 21711 YouTube, 22249 Facebook, 39138 Flickr, 1109681 VK.", "items": { "type": "string" } }, "types": { "title": "Mention types", "type": "array", "description": "Mentions and analytics. Posts, comments, or both.", "items": { "type": "string", "enum": [ "post", "comment" ], "enumTitles": [ "Posts", "Comments" ] } }, "channels": { "title": "Channels", "type": "array", "description": "Mentions and analytics. Owned or earned channels. Not available on all projects.", "items": { "type": "string", "enum": [ "earned", "owned" ], "enumTitles": [ "Earned", "Owned" ] } }, "reviewStatuses": { "title": "Human review status", "type": "array", "description": "Mentions and analytics. Reviewed, unreviewed or deleted mentions.", "items": { "type": "string", "enum": [ "unreviewed", "reviewed", "deleted" ], "enumTitles": [ "Unreviewed", "Reviewed", "Deleted" ] } }, "twitterTypes": { "title": "X (Twitter) types", "type": "array", "description": "Mentions and analytics. Keep only retweets or quoted retweets.", "items": { "type": "string", "enum": [ "retweet", "quoted-retweet" ], "enumTitles": [ "Retweets", "Quoted retweets" ] } }, "authorIds": { "title": "Author IDs", "type": "array", "description": "Mentions and analytics. Synthesio author IDs, as the author_id column of the mentions mode shows them, such as 22249-169446945261.", "items": { "type": "string" } }, "sourceIds": { "title": "Source IDs", "type": "array", "description": "Mentions and analytics. Synthesio source IDs (a page, channel or account), such as 21711-4202553.", "items": { "type": "string" } }, "mentionIds": { "title": "Mention IDs", "type": "array", "description": "Mentions. Read these mentions only, by Synthesio mention ID such as 38298-55237514657.", "items": { "type": "string" } }, "extraFilters": { "title": "Extra filters", "type": "object", "description": "Mentions and analytics. Any other documented filter as JSON, merged over the fields above: influence, synthesio_rank, ratings_normalized, classifiers, classifier_tags, communities, influencers, titles, collaboration filters, author demographics (author_genders, author_ages, author_affinities and the rest) and boolean must, should and must_not sets. Example: {\"influence\": {\"begin\": 250}}." }, "sortField": { "title": "Sort mentions by", "enum": [ "date", "crawled_at", "influence", "infused_at", "review.date", "synthesio_rank" ], "type": "string", "description": "Mentions. The documented sort fields.", "default": "date" }, "sortOrder": { "title": "Sort order", "enum": [ "desc", "asc" ], "type": "string", "description": "Mentions. Descending or ascending.", "default": "desc" }, "highlight": { "title": "Highlight matches", "type": "boolean", "description": "Mentions. Ask for highlighted excerpts based on the query, or on the project topics when no query is set. The excerpt goes into the snippet column.", "default": false }, "analyticsField": { "title": "Analytics field", "enum": [ "date", "infused_at", "crawled_at", "sentiment", "language", "country", "site", "site_type", "source", "author", "tags", "hashtags", "urls", "title", "type", "channel", "classifiers", "classifier_tags", "communities", "profile", "human_review_status", "collaboration_status", "collaboration_user", "author.demographics.gender", "author.demographics.age", "author.demographics.affinity_list", "author.demographics.job_list", "author.demographics.bio_tag_list", "author.demographics.family_status", "author.demographics.marital_status", "author.demographics.language_list", "author.location.city", "author.location.state", "influence", "synthesio_rank", "interactions.total_interactions", "interactions.total_active", "interactions.total_passive" ], "type": "string", "description": "Analytics. The field to count by. Date fields give a histogram over time; the others count mentions per value; influence, synthesio_rank and the interaction fields sum a metric.", "default": "date" }, "analyticsType": { "title": "Analytics type", "enum": [ "default", "terms", "date_histogram", "sum", "avg", "min", "max", "stats" ], "type": "string", "description": "Analytics. Leave on default to use the documented type of the field, or force terms (count per value), a date histogram, or a sum, average, min, max or stats of a numeric field.", "default": "default" }, "analyticsBy": { "title": "Break down by", "enum": [ "none", "date", "infused_at", "crawled_at", "sentiment", "language", "country", "site", "site_type", "source", "author", "tags", "hashtags", "urls", "title", "type", "channel", "classifiers", "classifier_tags", "communities", "profile", "human_review_status", "collaboration_status", "collaboration_user", "author.demographics.gender", "author.demographics.age", "author.demographics.affinity_list", "author.demographics.job_list", "author.demographics.bio_tag_list", "author.demographics.family_status", "author.demographics.marital_status", "author.demographics.language_list", "author.location.city", "author.location.state", "influence", "synthesio_rank", "interactions.total_interactions", "interactions.total_active", "interactions.total_passive" ], "type": "string", "description": "Analytics. A second field inside each bucket of the first, such as sentiment per day. A metric field such as influence sums inside each bucket.", "default": "none" }, "interval": { "title": "Interval", "type": "string", "description": "Analytics on a date field. day, week, month, year, a duration such as 2d or 12h, or milliseconds. Defaults to day." }, "timeZone": { "title": "Time zone", "type": "string", "description": "Analytics on a date field. A name such as Europe/Paris (handles daylight saving) or an offset such as -02:30. Hour intervals are always UTC." }, "topN": { "title": "Top N values", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Analytics on a terms field. The most distinct values to return, such as the top 20 sites. Empty returns all." }, "maxResults": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most rows this run returns and charges for. Mentions page up to 1,000 at a time.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 60, "type": "integer", "description": "Pacing. The provider does not publish a rate limit; rate limited calls are retried with a wait.", "default": 30 }, "apiKey": { "title": "Access token", "type": "string", "description": "A Synthesio OAuth access token (they last three hours). Stored as a secret. You can instead set the DATA_API_KEY environment secret, or give the four sign-in fields below so the actor fetches a fresh token itself." }, "clientId": { "title": "Client ID", "type": "string", "description": "The client ID of your Synthesio API application, from your Synthesio sales contact. Used with the client secret, login and password when no access token is given. Falls back to the DATA_API_CLIENT_ID environment secret." }, "clientSecret": { "title": "Client secret", "type": "string", "description": "The client secret of your Synthesio API application. Falls back to the DATA_API_CLIENT_SECRET environment secret." }, "username": { "title": "Login", "type": "string", "description": "The login (email) of the Synthesio user the token acts for. Falls back to the DATA_API_USERNAME environment secret." }, "password": { "title": "Password", "type": "string", "description": "That user's Synthesio password. Sent only to the Synthesio token endpoint. Falls back to the DATA_API_PASSWORD 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 } } } } } } } } } }