{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Research Service",
    "description": "Research TikTok promotion of a competitor or product in supported markets. Export messages, activity dates and source links for comparison. Paid-ad evidence and public activity are labelled separately.",
    "version": "0.1",
    "x-build-id": "BgjaIwE989nrVFqVr"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/diamade~tiktok-ads-research-service/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-diamade-tiktok-ads-research-service",
        "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/diamade~tiktok-ads-research-service/runs": {
      "post": {
        "operationId": "runs-sync-diamade-tiktok-ads-research-service",
        "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/diamade~tiktok-ads-research-service/run-sync": {
      "post": {
        "operationId": "run-sync-diamade-tiktok-ads-research-service",
        "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": [
          "query"
        ],
        "properties": {
          "researchType": {
            "title": "What do you want to research?",
            "enum": [
              "product_topic",
              "specific_competitor"
            ],
            "type": "string",
            "description": "Product / Topic gathers source-matched research results for your subject, with optional semantic narrowing of paid ads. Specific Competitor resolves an advertiser or related brand cluster in Ads Library markets. In US/Ukraine it researches a brand-name public query or a selected exact public creator; this does not verify legal advertiser identity, brand ownership or paid sponsorship."
          },
          "query": {
            "title": "Product, topic, keyword, or competitor",
            "pattern": ".*\\S.*",
            "minLength": 1,
            "maxLength": 200,
            "type": "string",
            "description": "Enter the phrase exactly as you want it researched, for example running shoes, electric vehicles, or Nike. For a competitor, use the clearest brand or legal advertiser name you know. The original text is preserved in the output."
          },
          "queries": {
            "title": "Add more products or topics (optional)",
            "uniqueItems": true,
            "type": "array",
            "description": "Product / Topic only. Each extra phrase is searched independently. Results merge by item ID without duplicate row charges. Searches follow list order and share one global result limit across countries (Preview: 12 total). More phrases can increase runtime and cost. Leave empty for Specific Competitor and Watch.",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": ".*\\S.*"
            }
          },
          "countryMode": {
            "title": "Market coverage",
            "enum": [
              "ALL_SUPPORTED_COUNTRIES",
              "EXPLICIT_COUNTRY_SET"
            ],
            "type": "string",
            "description": "All supported countries searches the 32-market Ads Library set. Selected countries also offers United States and Ukraine through public TikTok search and available curated paid Creative Center Top Ads. Requested publication dates filter public videos and skip curated paid Top Ads. The search market does not prove creator location or ad targeting."
          },
          "countries": {
            "title": "Selected countries",
            "maxItems": 34,
            "uniqueItems": true,
            "type": "array",
            "description": "Used only with Selected countries. Ukraine and United States: with requested dates, only public videos with known publication dates in that interval are collected; curated paid Top Ads are skipped. Without dates, both available sources may contribute. Leave empty with All 32 European markets.",
            "items": {
              "type": "string",
              "enum": [
                "AT",
                "BE",
                "BG",
                "HR",
                "CY",
                "CZ",
                "DK",
                "EE",
                "FI",
                "FR",
                "DE",
                "GR",
                "HU",
                "IS",
                "IE",
                "IT",
                "LV",
                "LI",
                "LT",
                "LU",
                "MT",
                "NL",
                "NO",
                "PL",
                "PT",
                "RO",
                "SK",
                "SI",
                "ES",
                "SE",
                "CH",
                "UA",
                "GB",
                "US"
              ],
              "enumTitles": [
                "Austria (AT)",
                "Belgium (BE)",
                "Bulgaria (BG)",
                "Croatia (HR)",
                "Cyprus (CY)",
                "Czechia (CZ)",
                "Denmark (DK)",
                "Estonia (EE)",
                "Finland (FI)",
                "France (FR)",
                "Germany (DE)",
                "Greece (GR)",
                "Hungary (HU)",
                "Iceland (IS)",
                "Ireland (IE)",
                "Italy (IT)",
                "Latvia (LV)",
                "Liechtenstein (LI)",
                "Lithuania (LT)",
                "Luxembourg (LU)",
                "Malta (MT)",
                "Netherlands (NL)",
                "Norway (NO)",
                "Poland (PL)",
                "Portugal (PT)",
                "Romania (RO)",
                "Slovakia (SK)",
                "Slovenia (SI)",
                "Spain (ES)",
                "Sweden (SE)",
                "Switzerland (CH)",
                "🇺🇦 Україна / Ukraine (UA)",
                "United Kingdom (GB)",
                "🇺🇸 United States (US)"
              ]
            }
          },
          "maxResults": {
            "title": "Maximum results (total)",
            "minimum": 1,
            "type": "integer",
            "description": "Full research only, including runs with an activity report. One total of unique activities across every country and query. Leave empty to collect source-available results without a user-set cap; this can take longer and cost more. Preview always uses 12 total: clear this field for Preview."
          },
          "fromDate": {
            "title": "From date",
            "pattern": "^(?:$|\\d{8}|\\d{2}[./]\\d{2}[./]\\d{4}|\\d{4}-\\d{2}-\\d{2})$",
            "type": "string",
            "description": "Optional inclusive boundary. UA/US public videos use publication dates in UTC, not changes in views. Curated paid Top Ads are skipped when dates are requested. Other markets retain Ads Library time-window semantics. JSON also accepts DDMMYYYY, DD.MM.YYYY, and DD/MM/YYYY."
          },
          "toDate": {
            "title": "To date",
            "pattern": "^(?:$|\\d{8}|\\d{2}[./]\\d{2}[./]\\d{4}|\\d{4}-\\d{2}-\\d{2}|[Rr][Ee][Cc][Ee][Nn][Tt]|[Nn][Oo][Ww]|[Tt][Oo][Dd][Aa][Yy])$",
            "type": "string",
            "description": "Optional inclusive boundary. UA/US public videos use publication dates in UTC. Empty includes the most recent available publications. API/JSON also accepts DDMMYYYY, DD.MM.YYYY, DD/MM/YYYY, recent, now, or today."
          },
          "researchMode": {
            "title": "Research mode",
            "enum": [
              "preview",
              "full",
              "report"
            ],
            "type": "string",
            "description": "Preview samples up to 12 unique activities with no result or report event fees. Full research returns source-labeled rows. Both stream typed rows to the default Dataset; Add activity report creates extra documents from those same rows without rerunning research. Existing prices are shown in the Pricing tab. Older API researchMode=report is accepted as Full with an activity report."
          },
          "advertiserReport": {
            "title": "Add activity report",
            "type": "boolean",
            "description": "Create extra Summary or Detailed HTML, TXT and JSON documents from the same collected rows. The default Dataset still streams typed research rows; there is no rerun or duplicate row charge. Choose the report level below; it is used only when this option is enabled. Full successful country reports use one report fee: currently $0.25 for either level. The planned $10 UA/US Detailed introductory fee has no scheduled date and starts only once native pricing becomes effective, replacing Summary's fee. Base-row and supported paid-ad enrichment charges remain additional. Public rows use the same base-row tariff, retain public-activity labels, and incur no semantic/Detail fee when unenriched. Preview has no result/report event fees. Check live Pricing. US/Ukraine reports summarize delivered public activity; Ads Library reports require Specific Competitor."
          },
          "reportLevel": {
            "title": "Activity report: Summary or Detailed",
            "enum": [
              "summary",
              "detailed"
            ],
            "type": "string",
            "description": "Used only when Add activity report is enabled. UA/US Summary includes scope, totals, hashtags and most active creators. Detailed also lists collected public publications, dates, available counters and links. Both currently retain the existing $0.25 successful country-report fee. A $10 introductory UA/US Detailed price is planned, with no scheduled date, and starts only when native pricing becomes effective; it replaces Summary's fee. Base research-row charges remain additional. European advertiser reports retain their existing presentation and Summary fee. Counters are recorded lifetime values, not views gained within the selected period. Preview has no result/report event fees. Check the live Pricing tab before running."
          },
          "relevantOnly": {
            "title": "Narrow paid rows by semantic relevance (optional)",
            "type": "boolean",
            "description": "OFF by default. Narrows Product / Topic paid ads only; it does not filter public-video matches. Specific Competitor uses identity instead."
          },
          "detail": {
            "title": "Add per-ad Detail",
            "type": "boolean",
            "description": "May be enabled alongside an activity report. Successful Detail adds available destination, CTA, campaign goal, targeting, and media information to the same supported paid-ad row. Public videos do not receive paid-ad Detail or its fee. If unavailable, the valid base row remains with an explanation."
          },
          "resultMode": {
            "title": "Legacy API collection mode",
            "type": "string",
            "description": "For older API inputs without researchMode. New inputs use Research mode."
          },
          "outputMode": {
            "title": "Legacy API output mode",
            "type": "string",
            "description": "For older API inputs without researchMode. New inputs use Research mode."
          },
          "creatorTopLimit": {
            "title": "Most active creators: maximum entries (optional)",
            "minimum": 1,
            "type": "integer",
            "description": "Report ranking only. Leave empty for all observed creators. Does not remove source rows or change report totals."
          },
          "creatorMinViews": {
            "title": "Most active creators: minimum recorded views (optional)",
            "minimum": 0,
            "type": "integer",
            "description": "Report ranking only. Uses available recorded lifetime views, never views gained within the chosen period. Leave empty for no threshold. Original rows and report totals remain unchanged."
          },
          "competitorClusterId": {
            "title": "Competitor / creator selection ID",
            "type": "string",
            "description": "Optional. In UA/US, copy competitorSelectionId from a returned public video to limit the same brand query to that exact creator. This is a creator selection, not proof of brand ownership. In Ads Library markets, use the verified cluster ID returned by a refinement request. Leave empty to research the full matching activity."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}