{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Dataset Monitor & Alerts", "description": "Monitor TikTok Ads Library exports for competitor changes. Detect new ads and verified changes to creatives, copy, CTAs, landing pages, targeting, reach and status. Use authorized Apify Datasets or JSON—no TikTok API key, browser, proxy or extractor lock-in; ready for schedules and webhooks.", "version": "0.1", "x-build-id": "RMX8dt2SB0X6R2Y9f" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automa-flow~tiktok-ads-dataset-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automa-flow-tiktok-ads-dataset-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/automa-flow~tiktok-ads-dataset-monitor/runs": { "post": { "operationId": "runs-sync-automa-flow-tiktok-ads-dataset-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/automa-flow~tiktok-ads-dataset-monitor/run-sync": { "post": { "operationId": "run-sync-automa-flow-tiktok-ads-dataset-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", "properties": { "datasetIds": { "title": "Source Datasets", "maxItems": 10, "type": "array", "description": "Select one Dataset for a normal run, or several Datasets that independently describe the same advertiser/query inventory for immediate corroboration." }, "datasetMonitorId": { "title": "Dataset monitor ID", "maxLength": 128, "type": "string", "description": "Required with Source Datasets. Stable ID for the one advertiser/query inventory represented by those Datasets." }, "datasetSourceNames": { "title": "Dataset source names", "maxItems": 10, "type": "array", "description": "Optional stable provider names in the same order as Source Datasets. Leave empty to use apify-dataset-1, apify-dataset-2, and so on.", "items": { "type": "string", "maxLength": 128 } }, "datasetExternalId": { "title": "Dataset external ID", "maxLength": 200, "type": "string", "description": "Optional CRM, client or brand identifier echoed into every output row for this Dataset monitor." }, "datasetIsComplete": { "title": "Full Dataset inventory retrieved", "type": "boolean", "description": "Enable only when every selected upstream Dataset completed all required pagination. Otherwise the Actor reports PARTIAL and retains state.", "default": false }, "datasetAuthoritativeStatus": { "title": "Trust Dataset active/inactive status", "type": "boolean", "description": "Enable only when every selected Dataset provider documents its active/inactive field as authoritative. Absence is never authoritative.", "default": false }, "feeds": { "title": "Inline TikTok Ads snapshots", "maxItems": 200, "type": "array", "description": "Optional inline snapshots for API payloads, explicit upstream failures, or several monitor inventories in one batch. Reuse monitorId across sources that corroborate one another.", "items": { "type": "object", "required": [ "monitorId", "sourceName" ], "properties": { "monitorId": { "title": "Monitor ID", "description": "Stable identifier for one advertiser/query inventory. Feeds with the same monitorId corroborate one another.", "type": "string", "editor": "textfield", "maxLength": 128 }, "externalId": { "title": "Your external ID", "description": "Optional CRM, client or brand identifier echoed into output rows.", "type": "string", "editor": "textfield", "maxLength": 200 }, "sourceName": { "title": "Source name", "description": "Stable provider/workflow name used as evidence, for example agency-export or approved-api.", "type": "string", "editor": "textfield", "maxLength": 128 }, "observations": { "title": "Inline ad observations", "description": "Ad rows pasted or sent through the API. Common camelCase and snake_case TikTok export fields are normalized automatically.", "type": "array", "editor": "json", "maxItems": 10000, "items": { "type": "object" } }, "status": { "title": "Upstream status", "description": "SUCCESS means the upstream request worked. PARTIAL and FAILED are preserved as failures and never converted into an empty inventory.", "type": "string", "editor": "select", "enum": [ "SUCCESS", "PARTIAL", "FAILED" ], "enumTitles": [ "Success", "Partial", "Failed" ], "default": "SUCCESS" }, "isComplete": { "title": "Full inventory retrieved", "description": "Enable only when the upstream completed every required page for this monitor. Without this explicit assertion the feed is PARTIAL and cannot advance state.", "type": "boolean", "default": false }, "authoritativeStatus": { "title": "Trust explicit active/inactive status", "description": "Enable only when this source documents its active/inactive field as authoritative. Absence from a result list is never authoritative.", "type": "boolean", "default": false }, "priority": { "title": "Source priority", "description": "Lower numbers win when sources expose different field coverage for the same ad. Keep one stable primary source across runs.", "type": "integer", "editor": "number", "minimum": 1, "maximum": 1000, "default": 100 }, "declaredTotal": { "title": "Upstream total ads", "description": "Optional completeness check. If it differs from the normalized unique ad count, the feed becomes PARTIAL.", "type": "integer", "editor": "number", "minimum": 0 }, "providerRunId": { "title": "Provider run ID", "description": "Optional upstream run identifier retained in monitor evidence.", "type": "string", "editor": "textfield", "maxLength": 200 }, "sourceUrl": { "title": "Source verification URL", "description": "Optional human-verification URL for this snapshot.", "type": "string", "editor": "textfield", "maxLength": 2048 } } } }, "mode": { "title": "Mode", "enum": [ "monitor", "snapshot" ], "type": "string", "description": "monitor reads and advances last-successful KVS state. snapshot only normalizes the supplied data and never touches state.", "default": "monitor" }, "outputMode": { "title": "Ad event output", "enum": [ "changesOnly", "all" ], "type": "string", "description": "changesOnly emits BASELINE, candidates and confirmed changes. all also emits UNCHANGED ads. Every monitor always gets one status row.", "default": "changesOnly" }, "verificationMode": { "title": "Change verification", "enum": [ "safe", "fast" ], "type": "string", "description": "safe requires two independent sources or the same source on two consecutive complete runs. fast confirms a change from one complete feed but still never infers inactivity from absence.", "default": "safe" }, "stateNamespace": { "title": "Monitoring history ID", "maxLength": 64, "type": "string", "description": "Separates histories when two Tasks reuse the same monitorId values. Keep unchanged across scheduled runs.", "default": "default" }, "maxItemsPerDataset": { "title": "Maximum rows per input Dataset", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Safety and KVS bound. A larger Dataset is reported PARTIAL rather than silently truncated; split it into monitor scopes.", "default": 5000 } } }, "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 } } }, "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 } } } } } } } } } }