{
  "openapi": "3.0.1",
  "info": {
    "title": "AEO Citation Monitor — Brand Tracking in AI Search",
    "description": "Monitor how your brand appears in AI search responses. Submits prompts to ChatGPT, Claude, Gemini, Perplexity, xAI Grok, and Google AI Overviews; emits structured records of brand mentions, cited URLs, competitor positions, and list-rank position. Pay-per-resolution pricing.",
    "version": "0.1",
    "x-build-id": "HiQmuGVdvkS0mT9Qh"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/glaciological_hexahedron~aeo-citation-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-glaciological_hexahedron-aeo-citation-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/glaciological_hexahedron~aeo-citation-monitor/runs": {
      "post": {
        "operationId": "runs-sync-glaciological_hexahedron-aeo-citation-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/glaciological_hexahedron~aeo-citation-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-glaciological_hexahedron-aeo-citation-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",
        "required": [
          "brand",
          "providers",
          "acknowledgePublicBrandsOnly"
        ],
        "properties": {
          "brand": {
            "title": "Your brand",
            "type": "object",
            "description": "The brand you want to track. List every spelling variant — abbreviations, legal name, ticker — under aliases so all mentions are caught."
          },
          "competitors": {
            "title": "Competitors to track",
            "type": "array",
            "description": "Optional. AI engines often mention multiple brands in one response — listing competitors here surfaces which ones get cited alongside yours.",
            "default": []
          },
          "template": {
            "title": "Vertical template",
            "enum": [
              "saas-b2b",
              "ecommerce-d2c",
              "local-services",
              "agency",
              "media-publisher",
              "fintech"
            ],
            "type": "string",
            "description": "Pick a built-in prompt set for your industry. Each template generates ~25 prompts grouped by intent (comparison, discovery, pricing, etc.). Leave empty if you'll write your own prompts below.",
            "default": "ecommerce-d2c"
          },
          "templateVariables": {
            "title": "Customize the template",
            "type": "object",
            "description": "Fill in variables used by the template (e.g., {category}, {audience}, {year}). Most buyers only need to set 'category'. Look at the template's prompts to see what variables it uses."
          },
          "prompts": {
            "title": "Custom prompts (optional)",
            "maxItems": 500,
            "type": "array",
            "description": "Add your own prompts to run alongside (or instead of) the template's prompts. One prompt per line. Cap: 500 per run.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "providers": {
            "title": "AI engines to query",
            "minItems": 1,
            "uniqueItems": true,
            "type": "array",
            "description": "Which AI search engines to check. The default 4 fast engines complete in <60s per prompt; add 'openai' and 'google-gemini' for full 6-engine coverage at the cost of longer wall-clock (grounded ChatGPT and Gemini calls take 60-180s each).",
            "default": [
              "perplexity",
              "anthropic",
              "xai-grok",
              "google-aio"
            ],
            "items": {
              "type": "string"
            }
          },
          "locale": {
            "title": "Country / language",
            "type": "object",
            "description": "Optional. Bias responses toward a country (ISO 3166-1 alpha-2: US, GB, DE, FR, JP) and language (ISO 639-1: en, de, fr, ja). Used natively for Perplexity/OpenAI/AI Overviews; passed as a system prompt for Anthropic/Gemini/Grok."
          },
          "enableSentimentTagging": {
            "title": "Tag mentions with sentiment (positive / neutral / negative)",
            "type": "boolean",
            "description": "Adds 3-class sentiment classification per mention context. Useful for measuring whether the AI describes your brand positively or negatively. Adds $0.005 per record.",
            "default": false
          },
          "discoverPromptsFromUrl": {
            "title": "Auto-discover prompts from a URL",
            "type": "string",
            "description": "Alternative to writing prompts: give us your brand's homepage URL, and the Actor reads the content and auto-generates 10-15 likely prompts your customers would ask. Charged $0.05 once per run."
          },
          "acknowledgePublicBrandsOnly": {
            "title": "I confirm I'm tracking a public brand, not a private individual",
            "type": "boolean",
            "description": "REQUIRED. Anthropic and OpenAI's terms prohibit using their APIs for surveillance, tracking, or profiling of individuals. This Actor is for tracking public brands, products, services, and topics in AI responses.",
            "default": true
          },
          "providerConfig": {
            "title": "Per-provider settings (advanced)",
            "type": "object",
            "description": "Override defaults per provider. Most useful: providerConfig.openai.useWebSearch (default true; flip to false for cheaper training-only ChatGPT signal). See README for full schema."
          },
          "maxBudgetUsd": {
            "title": "Pre-flight budget cap (USD)",
            "minimum": 1,
            "type": "integer",
            "description": "Refuse to start the run if the upper-bound cost estimate exceeds this. Useful guard for big template-driven runs."
          },
          "maxResolutions": {
            "title": "Hard cap on records (= prompts × providers)",
            "minimum": 1,
            "type": "integer",
            "description": "Stops the run after N successful records. Use with templates if you want only the first N prompts to run."
          },
          "maxConcurrentPrompts": {
            "title": "Parallel prompts",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many prompts to run in parallel. Higher = faster but more upstream API pressure. Default 3 is a good balance.",
            "default": 3
          },
          "perResolutionTimeoutMs": {
            "title": "Per-call timeout (milliseconds)",
            "minimum": 10000,
            "maximum": 900000,
            "type": "integer",
            "description": "Cap on any single (prompt × provider) call. Default 120000 (2 min) — bounds wall-clock when one provider hangs.",
            "default": 120000
          },
          "queryGroups": {
            "title": "Query groups (alternative to template)",
            "type": "array",
            "description": "Group prompts by name with [{groupName, queries[]}]. Familiar shape for buyers migrating from other AEO tools."
          },
          "promptCategories": {
            "title": "Prompt categories",
            "type": "object",
            "description": "Categorize your custom prompts for dashboard pivots. Each prompt may appear in multiple categories."
          },
          "includePositioningSummary": {
            "title": "Include positioning summary",
            "type": "boolean",
            "description": "Adds a one-line summary per resolution about how the brand was positioned. Adds a small utility-tier LLM call per record.",
            "default": false
          },
          "emitRawProviderResponse": {
            "title": "Include raw provider response",
            "type": "boolean",
            "description": "Add the verbatim provider response payload as rawProviderResponse for audit/replay. Adds $0.001 per record.",
            "default": false
          },
          "deltaMode": {
            "title": "Delta mode — only emit changed records",
            "type": "boolean",
            "description": "On second and subsequent runs of the same brand, emit only records whose content changed since last run. Useful for weekly tracking — saves you parsing identical responses.",
            "default": false
          },
          "deltaStateKey": {
            "title": "Delta state key (override)",
            "type": "string",
            "description": "Override for the KeyValueStore key holding cross-run delta state. Default: aeo-citation-monitor-{slug(brand.name)}-state."
          },
          "organizationId": {
            "title": "Organization tag",
            "type": "string",
            "description": "Pass-through tag for multi-tenant dashboards. Every record carries this value."
          },
          "runId": {
            "title": "Run ID override",
            "type": "string",
            "description": "Optional explicit UUID. Default: a fresh v4 UUID per run."
          },
          "bypassToSGuard": {
            "title": "Bypass ToS heuristic guard",
            "type": "boolean",
            "description": "Bypass the heuristic prompt-validation guard that flags honorific patterns (Mr./Mrs./Dr./...). Use only with documented authorization (e.g., authorized journalism research).",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}