{ "openapi": "3.0.1", "info": { "title": "Stack Overflow & StackExchange Search", "description": "Search Stack Overflow and the StackExchange network for questions using the official StackExchange API v2.3. Extract questions with scores, answer counts, view counts, tags, and author details from nine popular Q&A communities.", "version": "2.0", "x-build-id": "b81sx8pJR0mVgR9lO" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~stackexchange-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-stackexchange-search", "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/ryanclinton~stackexchange-search/runs": { "post": { "operationId": "runs-sync-ryanclinton-stackexchange-search", "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/ryanclinton~stackexchange-search/run-sync": { "post": { "operationId": "run-sync-ryanclinton-stackexchange-search", "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": { "preset": { "title": "Preset", "enum": [ "standard", "ai-training", "monitoring", "research", "seo-content", "for-startups", "for-content-creators", "for-devrel", "for-llm-builders" ], "type": "string", "description": "Workflow preset that pre-configures sensible defaults. Explicit fields below always override the preset.\n\nTask-based:\n• standard — plain search, no enrichment, backwards-compatible.\n• ai-training — emits LLM-ready Q&A pairs with attribution.\n• monitoring — daily watchdog. Returns only new since last run, fires alerts on spikes, emits decision record.\n• research — gap analysis + topic mapping with intelligence + problem clusters + decision summary.\n• seo-content — content opportunities + trending topics + ranked decision record.\n\nPersona-based:\n• for-startups — daily product-mention monitoring with alerts + decision.\n• for-content-creators — content gap discovery with problem clusters + decision.\n• for-devrel — Developer-Relations monitoring with best-answer detection + alerts.\n• for-llm-builders — same as ai-training with stricter quality defaults.", "default": "standard" }, "query": { "title": "Search Query", "type": "string", "description": "Free-text search across question titles and bodies. Leave blank to search by tags only — do NOT combine an unintended query with a tag filter (it AND-narrows to zero)." }, "site": { "title": "Site", "enum": [ "stackoverflow", "serverfault", "superuser", "askubuntu", "softwareengineering", "codereview", "dba", "webmasters", "webapps", "ux", "gamedev", "math", "stats", "datascience", "ai", "cs", "security", "crypto", "reverseengineering", "unix", "apple", "android", "raspberrypi", "electronics", "tex", "english", "writers", "money", "workplace", "academia" ], "type": "string", "description": "StackExchange site to search. Pick from the most popular 30; for any of the 170+ other sites, leave this and use Custom Site below.", "default": "stackoverflow" }, "customSite": { "title": "Custom Site (overrides Site)", "type": "string", "description": "Any StackExchange API site name not in the dropdown — e.g. 'gaming', 'cooking', 'photo', 'parenting', 'aviation', 'mathoverflow.net'. Find the full list at https://api.stackexchange.com/docs/sites. When set, this overrides the Site dropdown." }, "tagged": { "title": "Required Tags", "type": "string", "description": "Semicolon-separated tags — questions must have ALL listed tags. Example: python;web-scraping" }, "notTagged": { "title": "Excluded Tags", "type": "string", "description": "Semicolon-separated tags to exclude. Example: javascript;jquery — drops any question with these tags." }, "sortBy": { "title": "Sort By", "enum": [ "votes", "activity", "creation", "relevance" ], "type": "string", "description": "How to sort results.", "default": "votes" }, "answeredOnly": { "title": "Answered Only", "type": "boolean", "description": "Only return questions that have an accepted answer." }, "minScore": { "title": "Minimum Score", "minimum": -100, "maximum": 100000, "type": "integer", "description": "Drop questions whose score is below this number. Useful for quality filtering — e.g. 10 to keep only well-voted questions." }, "fromDate": { "title": "From Date", "type": "string", "description": "ISO date (YYYY-MM-DD). Only return questions created on or after this date. Leave blank for all-time." }, "toDate": { "title": "To Date", "type": "string", "description": "ISO date (YYYY-MM-DD). Only return questions created on or before this date." }, "includeBody": { "title": "Include Question Body", "type": "boolean", "description": "Fetch the full Markdown body of each question. Adds detail for AI training data and content analysis. (Same API call — no extra quota cost.)" }, "answersMode": { "title": "Answers Mode", "enum": [ "accepted", "top", "hybrid", "none" ], "type": "string", "description": "Which answers to fetch per question:\n• accepted — only the answer the asker accepted (default; cheapest).\n• top — fetch all answers and return the highest-scoring one.\n• hybrid — prefer accepted, but flag when the top-voted answer outranks it (the most useful default for AI training data).\n• none — skip answer enrichment entirely.", "default": "accepted" }, "includeAcceptedAnswer": { "title": "Include Accepted Answer Body", "type": "boolean", "description": "For questions with an accepted answer, fetch the answer's Markdown body, score, and author. Costs 1 extra API request per 100 answers." }, "enrichTagMetadata": { "title": "Enrich Tag Metadata", "type": "boolean", "description": "Add total usage count for each tag (helps rank tags by community size). Costs 1 extra API request per 100 unique tags." }, "includeIntelligence": { "title": "Compute Intelligence Scores", "type": "boolean", "description": "Add per-question quality, virality, discussion-depth, and difficulty scores (0–1). Pure math on existing fields — no extra API calls." }, "includeClusters": { "title": "Group Questions Into Tag Clusters", "type": "boolean", "description": "Assign each question a clusterId based on its most-frequent tag in this run. Cluster summary lands in the KV-store SUMMARY." }, "includeInsights": { "title": "Generate Run-Level Insights", "type": "boolean", "description": "Compute top problems (most-frequent tags), content opportunities (high-view, no-acceptance questions), and emerging topics (high-virality tags). Saved to KV-store SUMMARY, not the dataset." }, "includeProblemClusters": { "title": "Multi-Tag Problem Clusters", "type": "boolean", "description": "Group questions by their 2 most-frequent tags (e.g. 'react+hooks', 'kubernetes+ingress') instead of single dominant tag. More granular than tag clustering, surfaces problem patterns. Each question gets a problemClusterId / problemClusterLabel. Cluster summary lands in SUMMARY." }, "includeAlerts": { "title": "Alert Engine (cross-run)", "type": "boolean", "description": "Compare against the prior run's snapshot and emit alert records (recordType: 'alert') for tag spikes, unresolved-question surges, high-velocity score changes, dormant resurgences, and new problem clusters. Requires state — auto-loads on second run." }, "includeTrends": { "title": "Trend Engine (cross-run)", "type": "boolean", "description": "Compute per-tag trend direction (rising / stable / declining / new / gone) and velocity (0–1) by comparing current tag frequencies against the prior run. Saved to SUMMARY.trends." }, "includeDecision": { "title": "Decision Record (analyst-style summary)", "type": "boolean", "description": "Emit a single recordType: 'decision' record with topContentOpportunities, urgentProblems, trendingTopics, ignoredHighValueQuestions, recommendations, confidenceLevel, and decisionReadiness. Drop into Slack / agent tool calls / dashboards without parsing." }, "includeMethodology": { "title": "Include Intelligence Methodology", "type": "boolean", "description": "Add the formulas + weights used by the intelligence layer to the SUMMARY. Useful for trust + audit." }, "alertSpikeMultiplier": { "title": "Alert Spike Multiplier", "minimum": 1.1, "maximum": 10, "type": "number", "description": "Tag is flagged as a spike when current count ≥ this multiplier × prior count. Default 2.0 (doubled). Only used when 'Alert Engine' is on." }, "alertMinTagCount": { "title": "Alert Min Tag Count", "minimum": 1, "maximum": 100, "type": "integer", "description": "Minimum question count required before a tag can trigger a spike alert (suppresses noise from tiny sample sizes). Default 3." }, "correlateWithGithub": { "title": "Correlate with GitHub Repos", "type": "boolean", "description": "Calls our github-repo-search sub-actor on the top urgent problem clusters and attaches a 'githubContext' block (top repos, latest releases, abandoned status) to each cluster. When a recent release matches a 'breaking-change' or 'version-upgrade' root-cause hypothesis, the hypothesis confidence is BOOSTED with hard evidence. Significantly increases run cost — see correlateWithGithubMaxClusters / correlateWithGithubReposPerCluster below." }, "correlateWithGithubMaxClusters": { "title": "Max Clusters to Correlate", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum number of urgent clusters to look up on GitHub. Each cluster costs reposPerCluster × $0.15. Default 3 (so 3 × 3 × $0.15 = $1.35 max).", "default": 3 }, "correlateWithGithubReposPerCluster": { "title": "Repos Per Cluster", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of top repos to fetch per cluster. Default 3.", "default": 3 }, "githubToken": { "title": "GitHub Token (Optional)", "type": "string", "description": "Personal access token for higher GitHub API rate limits (5000 req/hr vs 60). Strongly recommended when correlateWithGithub is enabled with > 1 cluster. Create at github.com/settings/tokens — no special scopes needed." }, "githubActorId": { "title": "GitHub Sub-Actor ID (Override)", "type": "string", "description": "Override the github-repo-search actor ID. Defaults to ryanclinton/github-repo-search." }, "clusterCategoryFilter": { "title": "Cluster Category Filter", "enum": [ "all", "opportunity", "risk", "hybrid", "noise" ], "type": "string", "description": "Restrict the decision layer (urgentProblems, tasks, systemicIssues, tracker push) to clusters of a specific category. 'all' = no filter. Use 'risk' for engineering teams, 'opportunity' for content/docs teams, 'hybrid' for cross-functional. Question records are unaffected.", "default": "all" }, "rootCausePatternFilter": { "title": "Root-Cause Pattern Filter", "type": "array", "description": "Restrict the decision layer to clusters whose top root-cause pattern matches one of these. Empty = no filter. Useful for routing: docs teams filter to ['docs-gap', 'configuration', 'tooling-confusion']; product teams filter to ['breaking-change', 'version-upgrade', 'deprecated-api', 'platform-issue'].", "items": { "type": "string" } }, "pushTasksToTracker": { "title": "Push Tasks to Tracker (Auto-Create Tickets)", "enum": [ "none", "jira", "linear", "github" ], "type": "string", "description": "Auto-create tickets in your tracker for every task in the decision record. SAFETY: defaults to dry-run mode — set trackerDryRun: false to actually create tickets. Tasks are deduped via the apify-stackexchange-task:{id} label, but searching the tracker for existing items is your responsibility (re-running the same query may create duplicates). Recommended pattern: schedule with onlyPushShouldAct: true so only fully-validated tasks land in your backlog.", "default": "none" }, "trackerDryRun": { "title": "Tracker Dry-Run Mode", "type": "boolean", "description": "When true (default), no tickets are actually created — the actor simulates the push and writes a tracker-result record per task showing what WOULD have been created. Set to false ONLY when you've reviewed the dry-run output and are ready to create live tickets.", "default": true }, "onlyPushShouldAct": { "title": "Only Push shouldAct=true Tasks", "type": "boolean", "description": "When true, only tasks with shouldAct = true (causal score ≥ 0.7 + high severity + strong evidence + no warning contradictions) are pushed. Strongly recommended for production schedules." }, "jiraBaseUrl": { "title": "Jira Base URL", "type": "string", "description": "Your Jira workspace URL, e.g. https://your-company.atlassian.net. Required when pushTasksToTracker is 'jira'." }, "jiraEmail": { "title": "Jira Email", "type": "string", "description": "Email address associated with your Jira API token. Required when pushTasksToTracker is 'jira'." }, "jiraApiToken": { "title": "Jira API Token", "type": "string", "description": "API token from id.atlassian.com/manage-profile/security/api-tokens. Required when pushTasksToTracker is 'jira'." }, "jiraProjectKey": { "title": "Jira Project Key", "type": "string", "description": "Target Jira project key (e.g. ENG, OPS). Required when pushTasksToTracker is 'jira'." }, "jiraIssueType": { "title": "Jira Issue Type", "type": "string", "description": "Issue type name (e.g. 'Task', 'Bug', 'Story'). Defaults to 'Task'." }, "linearApiKey": { "title": "Linear API Key", "type": "string", "description": "API key from linear.app/settings/api. Required when pushTasksToTracker is 'linear'." }, "linearTeamId": { "title": "Linear Team ID", "type": "string", "description": "Linear team UUID. Find via the Linear API or in URLs. Required when pushTasksToTracker is 'linear'." }, "githubIssuesToken": { "title": "GitHub Issues Token", "type": "string", "description": "GitHub PAT with 'issues:write' scope. Required when pushTasksToTracker is 'github'. Different from githubToken (which is for sub-actor calls only)." }, "githubIssuesRepo": { "title": "GitHub Issues Repo (owner/repo)", "type": "string", "description": "Target repo in 'owner/repo' format, e.g. 'myorg/backlog'. Required when pushTasksToTracker is 'github'." }, "outputMode": { "title": "Output Mode", "enum": [ "standard", "llm-dataset", "decision" ], "type": "string", "description": "Shape of the dataset records.\n• standard — one record per question with question + answer fields.\n• llm-dataset — emits {recordType: 'llm-pair', instruction, context, response, metadata} records suitable for fine-tuning, RAG ingestion, or evaluation. Skips questions without a usable Q+A body pair.\n• decision — \"give me the answer, not the data\" mode. Suppresses individual question records and emits ONLY the decision record + alerts + tracker results. Same per-question PPE charge (analysis still runs); just a denser output. Ideal for AI agent tool calls, scheduled monitoring, exec dashboards.", "default": "standard" }, "bodyMaxChars": { "title": "Question Body Max Chars", "minimum": 200, "maximum": 100000, "type": "integer", "description": "Truncate question bodies to this character count. Useful for keeping LLM datasets under a token budget. Leave blank for no truncation." }, "answerMaxChars": { "title": "Answer Body Max Chars", "minimum": 200, "maximum": 100000, "type": "integer", "description": "Truncate answer bodies to this character count." }, "incremental": { "title": "Incremental Mode (Only New Since Last Run)", "type": "boolean", "description": "Persist seen question IDs in the run's key-value store. Subsequent runs return only questions that weren't seen before. Perfect for daily monitoring schedules. Capped at 5000 IDs (FIFO)." }, "incrementalKey": { "title": "Incremental State Key", "type": "string", "description": "Override the auto-generated state key. Use a stable string (e.g. 'so-python-daily') across scheduled runs so they share state. Default key is derived from site + query + tags." }, "detectChanges": { "title": "Detect Score / Acceptance Changes", "type": "boolean", "description": "Add a `change` object to each question with scoreDelta, answerCountDelta, and acceptedAnswerChanged vs the prior run. Implies state persistence (same as incremental mode)." }, "openaiApiKey": { "title": "OpenAI API Key (semantic features)", "type": "string", "description": "Required for semantic search, semantic dedup, or semantic clustering below. Get one at https://platform.openai.com/api-keys. Embeddings cost ~$0.02 per 1M tokens with the small model — a 100-question run typically costs under $0.001 in embedding fees." }, "embeddingModel": { "title": "Embedding Model", "enum": [ "text-embedding-3-small", "text-embedding-3-large" ], "type": "string", "description": "OpenAI embedding model. text-embedding-3-small is recommended for >95% of use cases ($0.02/1M tokens). text-embedding-3-large is more accurate at the boundary cases ($0.13/1M tokens).", "default": "text-embedding-3-small" }, "semanticQuery": { "title": "Semantic Query (Re-Rank Results)", "type": "string", "description": "Free-text intent description. Results are re-ranked by cosine similarity to this query's embedding. Each question gets `similarityToQuery` (0–1) and `semanticRank` fields. Useful when keyword search returns broad results — re-ranking surfaces the conceptually closest ones at the top." }, "semanticDedup": { "title": "Semantic Deduplication", "type": "boolean", "description": "Drop near-duplicate questions (same question asked many ways). Canonicals are flagged with `isCanonicalOfDuplicates` + `duplicateCount`. Critical for AI training datasets." }, "semanticDedupThreshold": { "title": "Dedup Similarity Threshold", "minimum": 0.5, "maximum": 0.99, "type": "number", "description": "Cosine similarity above which two questions are considered duplicates. Higher = stricter (only very close duplicates dropped). Default 0.92 catches most paraphrases without false positives.", "default": 0.92 }, "semanticClustering": { "title": "Semantic Topic Clustering", "type": "boolean", "description": "Group questions by semantic similarity (replaces tag-based clustering when both are on). Each question gets `semantic.semanticClusterId` and `semantic.semanticClusterLabel`. Cluster summary written to KV SUMMARY." }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of questions to return. Above 200 may consume a noticeable chunk of the 300/day anonymous StackExchange API quota.", "default": 30 } } }, "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 } } } } } } } } } }