{
  "openapi": "3.0.1",
  "info": {
    "title": "X (Twitter) Trends Scraper - Trending Topics by Country & City",
    "description": "Scrape X (Twitter) trending topics and hashtags for 467 places: worldwide, 62 countries, 400+ cities. The current top 50, the hourly timeline, rank change, history by date and hour, top lists. No X account, no login, no cookies. $0.09 per 1,000 trends.",
    "version": "0.1",
    "x-build-id": "Jeh10VNDfHSgflNsC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/topapi~x-trends-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-topapi-x-trends-scraper",
        "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/topapi~x-trends-scraper/runs": {
      "post": {
        "operationId": "runs-sync-topapi-x-trends-scraper",
        "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/topapi~x-trends-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-topapi-x-trends-scraper",
        "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": {
          "locations": {
            "title": "Places",
            "type": "array",
            "description": "Countries, towns, two-letter codes, WOEIDs or trends24 / getdaytrends links, one per line. E.g. \"United States\", \"New York, US\", \"JP\", \"23424977\", \"worldwide\".",
            "items": {
              "type": "string"
            }
          },
          "woeids": {
            "title": "WOEIDs",
            "type": "array",
            "description": "Yahoo Where On Earth IDs, as X uses them. E.g. 1 (worldwide), 23424977 (United States), 2459115 (New York). Turn on \"List the places\" to see all 467.",
            "items": {
              "type": "string"
            }
          },
          "listLocations": {
            "title": "List the places (instead of trends)",
            "type": "boolean",
            "description": "Return the 467 places X publishes trends for, with WOEID, country code and place type, instead of trends. Filter them with the three fields below.",
            "default": false
          },
          "listCountry": {
            "title": "List: country",
            "type": "string",
            "description": "With \"List the places\": keep the places in one country. E.g. \"Japan\" or \"JP\"."
          },
          "listPlaceType": {
            "title": "List: place type",
            "enum": [
              "country",
              "town",
              "worldwide"
            ],
            "type": "string",
            "description": "With \"List the places\": keep one kind of place."
          },
          "nameContains": {
            "title": "List: name contains",
            "type": "string",
            "description": "With \"List the places\": keep places whose name contains this text. E.g. \"san\"."
          },
          "includeHistory": {
            "title": "Every hourly list on trends24 (about 20 hours)",
            "type": "boolean",
            "description": "All the hourly lists trends24 keeps for the place (about 20 lists of 50, the last ~20 hours, ~1,000 rows per place), instead of the current list only.",
            "default": false
          },
          "timePeriods": {
            "title": "Time periods",
            "type": "array",
            "description": "Pick lists by age. Live = the latest list. 2 and 3 days ago come from the dated history (worldwide).",
            "items": {
              "type": "string",
              "enum": [
                "live",
                "1h",
                "3h",
                "6h",
                "12h",
                "24h",
                "2d",
                "3d"
              ],
              "enumTitles": [
                "Live",
                "1 hour ago",
                "3 hours ago",
                "6 hours ago",
                "12 hours ago",
                "24 hours ago",
                "2 days ago",
                "3 days ago"
              ]
            }
          },
          "hoursAgo": {
            "title": "Hours ago",
            "minimum": 0,
            "maximum": 23,
            "type": "integer",
            "description": "The one list from N hours ago (0 = now, up to 23)."
          },
          "date": {
            "title": "Date (UTC)",
            "type": "string",
            "description": "A past day, YYYY-MM-DD (or \"yesterday\", \"3 days ago\"). With an hour: that hour's list. Without: all 24 hourly lists of the day. Worldwide back to 2024-05-15."
          },
          "hour": {
            "title": "Hour (UTC)",
            "minimum": 0,
            "maximum": 23,
            "type": "integer",
            "description": "With a date: the hour of the list, 0-23 UTC."
          },
          "from": {
            "title": "From (UTC)",
            "type": "string",
            "description": "Start of a range of lists, e.g. \"2026-10-01\" or \"2026-10-01 06\". One list per step, up to \"To\"."
          },
          "to": {
            "title": "To (UTC)",
            "type": "string",
            "description": "End of the range (left out). Empty = up to now."
          },
          "every": {
            "title": "Every",
            "type": "string",
            "description": "Time between two lists of the range: 1h, 6h, 1d... Lists are hourly, so a step under 1 hour reads as 1 hour.",
            "default": "1h"
          },
          "queries": {
            "title": "Batch of place + date + hour",
            "type": "array",
            "description": "Many lookups in one run, each its own place and hour. E.g. [{\"location\": \"worldwide\", \"date\": \"2025-01-01\", \"hour\": 12}]."
          },
          "maxTrendsPerLocation": {
            "title": "Trends per list",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Top N of each list, 1-50 (X's list is 50 long).",
            "default": 50
          },
          "excludeHashtags": {
            "title": "Exclude hashtags",
            "type": "boolean",
            "description": "Keep only phrase trends, drop #hashtags.",
            "default": false
          },
          "onlyHashtags": {
            "title": "Hashtags only",
            "type": "boolean",
            "description": "Keep only #hashtags.",
            "default": false
          },
          "includeKeywords": {
            "title": "Must contain",
            "type": "array",
            "description": "Keep a trend only if its text contains one of these words (case-insensitive). E.g. \"election\", \"#nba\".",
            "items": {
              "type": "string"
            }
          },
          "excludeKeywords": {
            "title": "Must not contain",
            "type": "array",
            "description": "Drop trends whose text contains any of these words.",
            "items": {
              "type": "string"
            }
          },
          "dedupeTrends": {
            "title": "One row per trend per place",
            "type": "boolean",
            "description": "With several lists (history, periods, dates): keep only the newest row of each trend in each place.",
            "default": false
          },
          "readAllTowns": {
            "title": "Read every town",
            "type": "boolean",
            "description": "With keyword or hashtag filters, towns of a country whose own list has no match are skipped (cheaper, fewer empty pages). Turn on to read every town anyway.",
            "default": false
          },
          "trendDetails": {
            "title": "Trend record (add-on)",
            "type": "boolean",
            "description": "Add each trend's all-time record: best rank and when, the places it trends in now (with rank) and before. $0.001 per trend, once per trend name per run.",
            "default": false
          },
          "maxTrendDetails": {
            "title": "Max trend records",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Cap on trend records per run (the add-on).",
            "default": 50
          },
          "topLists": {
            "title": "Top lists",
            "type": "array",
            "description": "Add getdaytrends' top lists for each country or worldwide: longest trending and most tweeted, for the day, the week or the month.",
            "items": {
              "type": "string",
              "enum": [
                "longest-day",
                "longest-week",
                "longest-month",
                "tweeted-day",
                "tweeted-week",
                "tweeted-month"
              ],
              "enumTitles": [
                "Longest trending today",
                "Longest trending this week",
                "Longest trending this month",
                "Most tweeted today",
                "Most tweeted this week",
                "Most tweeted this month"
              ]
            }
          },
          "monitorMode": {
            "title": "Only new trends (monitor)",
            "type": "boolean",
            "description": "Return only trends not delivered for that place by earlier runs in the window below (with the 24-hour history: only lists newer than the last run's).",
            "default": false
          },
          "monitorWindowHours": {
            "title": "Monitor window (hours)",
            "minimum": 1,
            "maximum": 720,
            "type": "integer",
            "description": "A trend delivered within this many hours is not delivered again for the same place.",
            "default": 24
          },
          "monitorStoreName": {
            "title": "Monitor store name",
            "type": "string",
            "description": "Named key-value store that remembers what was delivered. Use one per schedule.",
            "default": "x-trends-monitor"
          },
          "resetMonitor": {
            "title": "Reset monitor",
            "type": "boolean",
            "description": "Forget what earlier runs delivered and start over.",
            "default": false
          },
          "maxItems": {
            "title": "Max rows",
            "minimum": 0,
            "type": "integer",
            "description": "Cap on rows for the whole run (trends + places). 0 or empty = no cap (all 467 places now = 23,350 rows)."
          },
          "constantFields": {
            "title": "Constant columns",
            "type": "object",
            "description": "Columns added to every row, e.g. {\"campaign\": \"q4\"}."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "The run reads the trackers on the platform's own connection first, then moves to an Apify datacenter and then a residential session only if a site refuses it. Your own proxy replaces the Apify ones.",
            "default": {
              "useApifyProxy": true
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Pages read at once.",
            "default": 6
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}