{ "openapi": "3.1.0", "info": { "title": "SocialCrawl API: Listening - Keyword Listeners", "version": "1.0.0", "description": "Unified social media data API - one API key, one consistent response format, 69 platforms, 678 endpoints. Power AI agents with clean social data.\n\nThis document covers the Listening - Keyword Listeners endpoints only (1 operations). The full contract for every platform is at https://www.socialcrawl.dev/v1/openapi.json, and every per-platform document is listed at https://www.socialcrawl.dev/openapi/index.json.", "contact": { "name": "SocialCrawl", "url": "https://www.socialcrawl.dev", "email": "socialcrawl@ridio.io" } }, "servers": [ { "url": "https://www.socialcrawl.dev/v1", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "API key authentication. Send your key in the `x-api-key` request header on every call. Create and manage keys in the dashboard." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The same API key sent as `Authorization: Bearer `, the default in most agents and HTTP tools. Same key, same rules; when both headers are sent, `x-api-key` wins." } }, "schemas": { "ErrorEnvelope": { "type": "object", "description": "Unified error response envelope. Every 4xx/5xx response returns this shape; `error.type` is a machine-readable code from the API's error catalog.", "properties": { "success": { "type": "boolean", "enum": [ false ], "example": false, "description": "Always false on an error response." }, "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MISSING_API_KEY", "INVALID_API_KEY", "INSUFFICIENT_CREDITS", "INVALID_REQUEST", "ENDPOINT_NOT_FOUND", "RESOURCE_NOT_FOUND", "CONCURRENCY_LIMIT", "UPSTREAM_ERROR", "SERVICE_UNAVAILABLE", "INTERNAL_ERROR", "METHOD_NOT_ALLOWED", "IDEMPOTENCY_KEY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_REPLAY_UNAVAILABLE", "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED", "COHORT_IDENTITY_CONFLICT", "COHORT_QUERY_NOT_CANCELLABLE", "COHORT_QUERY_NOT_READY", "COHORT_RESULT_TOO_LARGE", "PAYLOAD_TOO_LARGE", "RATE_LIMITED", "KEY_BUDGET_EXCEEDED", "RUN_NOT_FOUND", "RUN_STATE_CONFLICT", "RUN_EXPIRED", "NEEDS_ASYNC", "CURSOR_EXPIRED", "SCHEDULE_NOT_FOUND" ], "example": "INVALID_REQUEST", "description": "Machine-readable error code. The per-status `x-error-codes` list on each response narrows which codes that status can carry." }, "message": { "type": "string", "description": "Human-readable explanation of the error." }, "status": { "type": "integer", "description": "HTTP status code, echoed in the body." }, "doc_url": { "type": "string", "description": "Link to the docs page for this error code." }, "retryable": { "type": "boolean", "description": "Whether retrying the identical request can succeed. True for rate limits, concurrency limits, idempotency contention and transient upstream or server failures; false for every other code, including both 402s." }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional structured context. Omitted on ordinary errors. Both 402s carry `reason` (`balance_too_low` or `key_budget_reached`), `retry_will_succeed: false`, a one-sentence `next_step`, and `top_up_url` or `key_settings_url`; the GET endpoints add `credits_required`; a metered endpoint adds `pricing` (`\"ceiling\"` when the hold is the most the call can cost and the unused part is refunded, `\"exact\"` when the call is charged what it holds; measured on recent production calls), `credits_typical` (on a ceiling, what a call like this is usually charged), and, when a cheaper shape of the same request exists, `lower_cost_with`, `lower_cost_options` (`param`, `value` or null to leave it out, and `credits_required` with that change) and `credits_required_cheapest`. A `max_credits` page that switched to a cheaper form to fit (`threads/search` with `expand=false`) and still found the balance short adds `balance_fallback`: the `param` and `value` it switched to, and `credits_required` for the call as sent. A page-cap rejection carries `reason: \"page_limit\"` with `max_page`, `requested_page` and `narrow_with`. An `INVALID_REQUEST` that sends no member of a required one-of group carries `fields` (the parameters of that group) and a one-sentence `next_step`. Other endpoints use it for their own taxonomies, such as the comment-lookup not-found reasons." }, "status_url": { "type": "string", "format": "uri", "description": "Present on 5xx responses: the public status page, filtered to the platform when one is known." }, "incident": { "type": "object", "description": "Present on a 5xx response when an open public incident explains the failure.", "properties": { "id": { "type": "string", "example": "k3v9w2m8q1zt" }, "title": { "type": "string" }, "status": { "type": "string", "example": "investigating" }, "impact": { "type": "string", "example": "major" }, "url": { "type": "string", "format": "uri" } }, "required": [ "id", "title", "status", "impact", "url" ] } }, "required": [ "type", "message", "status", "doc_url" ] }, "credits_used": { "type": "integer", "description": "Net credits charged for this request. Error paths deduct-then-refund, so this is 0 in almost every case; a partial-coverage composite may keep the succeeded-leg cost." }, "credits_remaining": { "type": [ "integer", "null" ], "description": "Credits left after this request when established. Some unauthenticated errors use null; on a prebilling route whose attempted balance lookup fails, this field is omitted instead of fabricated." }, "request_id": { "type": "string", "description": "Unique request identifier - matches the X-Request-Id header. Quote it in support requests." } }, "required": [ "success", "error", "credits_used", "request_id" ] }, "MonitorAlertRule": { "description": "A numeric condition evaluated against a monitor run and, for change operators, a previous comparable run.", "properties": { "metric": { "description": "Dot path to a numeric key in the recipe's own result, for example `coverage` or `summary.total`. On a numbers-only monitor (created with `track`) the metric must be one of `track.metrics`, and an `items[].` metric is evaluated once per row: a fired alert then carries `row_id`. The special metric `rows_new` (numbers-only monitors only; it needs an `items[].` metric in `track.metrics` and is not itself tracked) counts the list rows this run has that the previous run did not: `{\"metric\":\"rows_new\",\"op\":\"gt\",\"value\":0}` alerts on any new post or video. It accepts only `gt` and `gte`, and is skipped on the first run. \"New\" means absent from the previous successful run's stored rows (capped at `max_rows`, default 100), so a row that drops off and returns later counts as new again. An empty-page run is refunded and is not a baseline, so on a sparse feed the first run that holds rows has no baseline and stays silent: the first new post after a quiet period may not alert. Use a daily cadence or leave `max_rows` headroom.", "type": "string" }, "op": { "enum": [ "gt", "lt", "gte", "lte", "abs_change_gt", "pct_change_gt", "pct_change_lt" ], "type": "string" }, "value": { "type": "number" }, "window": { "description": "Accepted and stored, but ignored: a change op always compares against the immediately preceding comparable run, whatever the value.", "enum": [ "1d", "1w" ], "type": "string" } }, "required": [ "metric", "op", "value" ], "type": "object" }, "EventEnvelope": { "description": "One event, identical in the feed and in every webhook batch. `id` is stable for one fact, so deduplicate on it.", "properties": { "id": { "description": "Deterministic event id: the same fact never mints a second event.", "example": "evt_k3m7q2xwcbvd4nph6trz5ycgda", "type": "string" }, "type": { "description": "Dot-delimited lower-case type. Types written today: `discover.progress`, `discover.accounts_ready`, `discover.completed`, `discover.partial`, `discover.paused`, `discover.failed`, `discover.new_rows`, `discover.new_accounts`, `discover.new_items`, `discover.run_skipped`, `discover.run_failed`, `endpoint.disabled`.", "example": "discover.completed", "type": "string" }, "api_version": { "example": "2026-10-01", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "cursor": { "description": "The feed position right after this event. Send it as `cursor` to read what came after; an event id works too.", "example": "c_MS4xMi4xNzkyNDA0OTA0", "type": "string" }, "subject": { "description": "The object the event is about, for example `{ kind: \"discover_run\", id: \"run_…\" }`.", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "metadata": { "type": [ "object", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ], "type": [ "object", "null" ] }, "data": { "description": "The event's facts. Discover events carry counts and ids, never keywords or row text.", "type": "object" }, "links": { "additionalProperties": { "type": "string" }, "description": "Absolute URLs to the subject, such as `run` and `results` (for example `https://www.socialcrawl.dev/v1/prism/discover/runs/run_...`), the same in the feed and in webhook batches. Events served before 26/10/2026 carried relative paths.", "type": "object" } }, "required": [ "id", "type", "api_version", "created_at", "cursor", "subject", "data", "links" ], "type": "object" }, "WebhookEndpoint": { "description": "A registered receiver. The signing secret is never part of it: it is returned once, by create and by rotate-secret.", "properties": { "id": { "example": "we_V1StGXR8Z5jdHi6BmyT", "type": "string" }, "url": { "example": "https://example.com/hooks/socialcrawl", "type": "string" }, "description": { "type": [ "string", "null" ] }, "types": { "description": "Subscribed event types: exact types, `ns.*` wildcards, or `*` for every type.", "items": { "type": "string" }, "type": "array" }, "subject_ids": { "description": "Only events about these subjects (a run or schedule id); null for every subject.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "status": { "enum": [ "enabled", "disabled" ], "type": "string" }, "disabled_reason": { "description": "`gone` (the receiver answered 410), `failing` (5 consecutive days of failed deliveries), `key_revoked` (the creating key was revoked or deleted) or `user` (set with PATCH). Null while enabled.", "enum": [ "gone", "failing", "key_revoked", "user", null ], "type": [ "string", "null" ] }, "failing_since": { "description": "Start of the current run of failed deliveries; null while healthy.", "format": "date-time", "type": [ "string", "null" ] }, "api_version": { "example": "2026-10-01", "type": "string" }, "secret_rotation": { "description": "Set during a rotation: until `previous_secret_expires_at` every delivery is signed with both secrets.", "properties": { "previous_secret_expires_at": { "format": "date-time", "type": "string" } }, "type": [ "object", "null" ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "next": { "description": "Ready relative URLs for the next calls.", "properties": { "attempts_url": { "type": "string" }, "events_url": { "type": "string" }, "rotate_secret_url": { "type": "string" }, "self_url": { "type": "string" }, "test_url": { "type": "string" } }, "type": "object" } }, "required": [ "id", "url", "types", "status", "api_version", "created_at" ], "type": "object" }, "WebhookAttempt": { "description": "One delivery attempt. `response_excerpt` is at most 1 KB of your receiver's answer.", "properties": { "id": { "type": "string" }, "delivery_id": { "description": "The batch's `webhook-id`, the same on every retry.", "type": "string" }, "test": { "type": "boolean" }, "status": { "description": "Your receiver's HTTP status; null for a timeout, a refused host, a network error or a secret that could not be opened.", "type": [ "integer", "null" ] }, "outcome": { "enum": [ "delivered", "failed", "gone", "retry_after", "timeout", "redirect", "refused_host", "secret_unavailable", "network_error" ], "type": "string" }, "duration_ms": { "type": [ "integer", "null" ] }, "response_excerpt": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "delivery_id", "test", "status", "outcome", "created_at" ], "type": "object" }, "EventBatch": { "description": "What every delivery carries, also for one event: at most 100 events or 256 KB. Each inner event keeps its own `id` and `cursor`; deduplicate on the inner ids. A test send marks its event `\"test\": true` with `\"cursor\": null`.", "properties": { "id": { "example": "bat_V1StGXR8Z5jdHi6BmyT", "type": "string" }, "type": { "const": "event.batch", "type": "string" }, "data": { "properties": { "events": { "items": { "$ref": "#/components/schemas/EventEnvelope" }, "maxItems": 100, "type": "array" } }, "required": [ "events" ], "type": "object" } }, "required": [ "id", "type", "data" ], "type": "object" }, "ListeningRuleAst": { "description": "A rule as a tree of `and`, `or`, `not`, `term`, `phrase` and `field` nodes, as the dry run returns it in `data.stream.groups[].ast`.", "anyOf": [ { "type": "object", "properties": { "and": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ListeningRuleAst" } } }, "required": [ "and" ], "additionalProperties": false }, { "type": "object", "properties": { "or": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/ListeningRuleAst" } } }, "required": [ "or" ], "additionalProperties": false }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/ListeningRuleAst" } }, "required": [ "not" ], "additionalProperties": false }, { "type": "object", "properties": { "term": { "type": "string", "minLength": 1 } }, "required": [ "term" ], "additionalProperties": false }, { "type": "object", "properties": { "phrase": { "type": "string", "minLength": 1 } }, "required": [ "phrase" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "lang", "country", "platform", "site", "community" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "field", "value" ], "additionalProperties": false } ] } } }, "tags": [ { "description": "Listening - price and validate a keyword or boolean topic listener with a dry run; listeners themselves ship in LRel2a", "name": "listening" } ], "paths": { "/listening/streams": { "post": { "description": "Prices and validates a listener without creating it. Send `dry_run=1` with the body a create will take: the answer holds the normalised listener with each group's rule as a tree and in words, the monthly estimate in credits and money (`data.estimate`), the per-lane plan (`data.plan`), the use screen's verdict (`data.screen`), `warnings` and `next_step`. Nothing is fetched, stored or charged, so a dry run carries no `Idempotency-Key`. The same call without `dry_run` answers a free 400 `not_released` naming LRel2a, which ships listeners. Routes of later releases answer the same way: `POST /v1/listening/streams` (LRel2a), `GET /v1/listening/streams` (LRel2a), `GET /v1/listening/streams/{id}` (LRel2a), `PATCH /v1/listening/streams/{id}` (LRel2a), `POST /v1/listening/streams/{id}/pause` (LRel2a), `POST /v1/listening/streams/{id}/resume` (LRel2a), `DELETE /v1/listening/streams/{id}` (LRel2a), `GET /v1/listening/streams/{id}/mentions` (LRel2a), `GET /v1/listening/streams/{id}/runs` (LRel2a), `POST /v1/listening/preview` (LRel2b), `GET /v1/listening/usage` (LRel2b).", "operationId": "listening_streams_dry_run", "parameters": [ { "description": "Required: price and validate only. `1` and `true` are the same.", "in": "query", "name": "dry_run", "required": true, "schema": { "enum": [ "1", "true" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "keywords": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "One group whose keywords are its searches, each matched as written; multi-word keywords are searched as quoted phrases. Exactly one of `keywords`, `rule` or `groups`." }, "rule": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "ast": { "$ref": "#/components/schemas/ListeningRuleAst" } }, "required": [ "ast" ], "additionalProperties": false } ], "description": "One group as boolean text (`AND`, `OR`, `NOT`, \"quoted phrases\", brackets), or `{ \"ast\": … }` in its place." }, "groups": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$" }, "rule": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "object", "properties": { "ast": { "$ref": "#/components/schemas/ListeningRuleAst" } }, "required": [ "ast" ], "additionalProperties": false } ] }, "keywords": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 } }, "context": { "type": "string", "minLength": 3, "maxLength": 2000 }, "exclude_terms": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "platforms": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40, "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin", "x" ] } }, "languages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "country": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string" } }, "tags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "maxLength": 100 } } }, "required": [ "id" ], "additionalProperties": false }, "description": "Several topics in one listener, each with a unique `id` and a `rule` or `keywords`, and optionally its own `context`, `exclude_terms`, `platforms`, `languages`, `country` and `tags`, which override the listener's for that group." }, "platforms": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40, "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin", "x" ] }, "description": "Platforms to watch. Google News is `news`; `x` is accepted for `twitter` and every answer says `twitter`." }, "context": { "type": "string", "minLength": 3, "maxLength": 2000, "description": "What kept posts must be about, naming the sense an ambiguous keyword has; 3 to 2000 characters." }, "schedule": { "additionalProperties": false, "properties": { "every": { "description": "How often the listener checks. `30m` only when every chosen platform is read newest first.", "enum": [ "30m", "1h", "3h", "6h", "1d", "7d" ], "type": "string" }, "max_credits_per_month": { "description": "The monthly cap in credits, never exceeded. Required on a create from an API key; a dry run without it still answers and recommends one.", "maximum": 10000000, "minimum": 1, "type": "integer" }, "max_credits_per_run": { "description": "The most one check may spend. Defaults to `data.estimate.max_credits_per_slot`.", "maximum": 10000000, "minimum": 1, "type": "integer" }, "name": { "description": "The listener's name.", "maxLength": 120, "minLength": 1, "type": "string" }, "start_at": { "description": "When the first check fires instead of at create, at most 90 days ahead.", "format": "date-time", "type": "string" } }, "required": [ "every", "name" ], "type": "object", "description": "How often the listener checks, its caps and its name. Required. `max_credits_per_month` is in credits; for a budget in money, divide it by `data.estimate.money_per_credit`." }, "search_in": { "anyOf": [ { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 } } } ], "description": "What to search on each platform: `posts`, `comments` on Reddit, `blog` and `news` on Naver. A list for every platform, or an object per platform." }, "languages": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" }, "description": "ISO 639-1 codes; a post whose language is unknown is kept." }, "country": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 codes of the posts or authors to keep." }, "exclude_country": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 codes of the posts or authors to drop." }, "unknown_country": { "enum": [ "keep", "drop" ], "type": "string", "default": "keep", "description": "Keep or drop a post whose country is unknown when `country` or `exclude_country` is set." }, "exclude_terms": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Drop posts that contain any of these terms." }, "exclude": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Account keys (`:`) or evidence ids to drop." }, "sponsored": { "enum": [ "exclude", "only", "keep" ], "type": "string", "default": "exclude", "description": "`exclude` (the listener's default) drops posts marked as ads or paid partnerships, `only` keeps only those, `keep` turns the filter off. Discover's default is `keep`." }, "relevance": { "enum": [ "filter", "score", "off" ], "type": "string", "default": "filter", "description": "`filter` drops posts the judge rejects, `score` keeps every match with its judgment, `off` does not judge. Judging is included in the price of each check." }, "relevance_definition": { "enum": [ "mentions", "about" ], "type": "string", "default": "mentions", "description": "`mentions` keeps posts that name the topic; `about` keeps posts mainly about it." }, "metadata": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "string", "maxLength": 200 }, "description": "Up to 20 string labels for your own use, returned unchanged; `client` groups usage." }, "draft": { "type": "boolean", "description": "Save the listener as a draft that does not run." }, "api_key_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Dashboard only: the key the listener's checks run as and its events carry." }, "new_listener": { "type": "boolean", "description": "Create a second listener even when an identical one exists." } }, "additionalProperties": false, "example": { "keywords": [ "Acme", "Acme Cloud" ], "platforms": [ "youtube", "reddit", "x", "news" ], "context": "Acme Inc., the cloud software company, not the cartoon brand", "schedule": { "every": "1h", "max_credits_per_month": 20000, "name": "Acme brand" } }, "required": [ "platforms", "schedule" ] } } }, "description": "The listener: keywords, a rule or groups, platforms, context and a schedule.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "credits_used": { "const": 0, "type": "integer" }, "data": { "type": "object", "properties": { "dry_run": { "type": "boolean", "const": true }, "stream": { "type": "object", "properties": { "groups": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rule": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "ast": { "$ref": "#/components/schemas/ListeningRuleAst" } }, "required": [ "ast" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exclude_terms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] } }, { "type": "null" } ] }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "ast": { "$ref": "#/components/schemas/ListeningRuleAst" }, "read_back": { "type": "string" } }, "required": [ "id", "rule", "keywords", "context", "exclude_terms", "platforms", "languages", "country", "tags", "ast", "read_back" ], "additionalProperties": false } }, "platforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] } }, "lanes": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] }, "lane": { "type": "string" }, "search_in": { "type": "string" }, "ordering": { "type": "string", "enum": [ "newest_first", "top_results", "window_sample" ] }, "label": { "type": "string" } }, "required": [ "platform", "lane", "search_in", "ordering", "label" ], "additionalProperties": false } }, "search_in": { "type": "object", "propertyNames": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schedule": { "type": "object", "properties": { "every": { "type": "string", "enum": [ "30m", "1h", "3h", "6h", "1d", "7d" ] }, "name": { "type": "string" }, "start_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "every", "name", "start_at" ], "additionalProperties": false }, "caps": { "type": "object", "properties": { "max_credits_per_month": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "max_credits_per_run": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "max_credits_per_month", "max_credits_per_run" ], "additionalProperties": false }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "exclude_country": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "unknown_country": { "type": "string", "enum": [ "keep", "drop" ] }, "exclude_terms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "exclude": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sponsored": { "type": "string", "enum": [ "exclude", "only", "keep" ] }, "relevance": { "type": "string", "enum": [ "filter", "score", "off" ] }, "relevance_definition": { "anyOf": [ { "type": "string", "enum": [ "mentions", "about" ] }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "draft": { "type": "boolean" }, "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "groups", "platforms", "lanes", "search_in", "context", "schedule", "caps", "languages", "country", "exclude_country", "unknown_country", "exclude_terms", "exclude", "sponsored", "relevance", "relevance_definition", "metadata", "draft", "api_key_id" ], "additionalProperties": false }, "estimate": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "slots_in_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "searches_per_slot": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "credits_per_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "credits_per_hour": { "type": "number", "minimum": 0 }, "depth_range_credits_per_month": { "type": "array", "prefixItems": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } ] }, "max_credits_per_slot": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recommended_max_credits_per_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "money_per_credit": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "const": "GBP" }, "basis": { "type": "string", "enum": [ "active_pack", "starter_list" ] } }, "required": [ "amount", "currency", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "money_per_month": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "const": "GBP" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, { "type": "null" } ] }, "expected_net_credits_per_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "by_platform": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] }, "lane": { "type": "string" }, "search_in": { "type": "string" }, "searches_per_slot": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checks_per_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "credits_per_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "coverage": { "type": "string", "enum": [ "newest_first", "top_results", "window_sample" ] }, "empty_pages_refunded": { "type": "boolean" }, "expected_skip_share": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "platform", "lane", "search_in", "searches_per_slot", "checks_per_month", "credits_per_month", "max_pages", "coverage", "empty_pages_refunded" ], "additionalProperties": false } }, "by_group": { "type": "array", "items": { "type": "object", "properties": { "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_per_month": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "group", "credits_per_month" ], "additionalProperties": false } }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "also_in_subject_id": { "type": "string" }, "also_in_group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "group", "also_in_subject_id", "also_in_group" ], "additionalProperties": false } }, "fill": { "type": "object", "properties": { "geo": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] }, "share": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "platform", "share" ], "additionalProperties": false } } }, "required": [ "geo" ], "additionalProperties": false } }, "required": [ "month", "slots_in_month", "searches_per_slot", "credits_per_month", "credits_per_hour", "depth_range_credits_per_month", "max_credits_per_slot", "recommended_max_credits_per_month", "money_per_credit", "money_per_month", "by_platform", "by_group", "duplicates" ], "additionalProperties": false }, "plan": { "type": "array", "items": { "type": "object", "properties": { "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "type": "string", "enum": [ "youtube", "reddit", "twitter", "news", "naver", "tiktok", "facebook", "threads", "linkedin" ] }, "lane": { "type": "string" }, "fetch_terms": { "type": "array", "items": { "type": "string" } }, "local": { "type": "array", "items": { "type": "string" } } }, "required": [ "group", "platform", "lane", "fetch_terms", "local" ], "additionalProperties": false } }, "screen": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "allowed", "refused", "unavailable" ] }, "target": { "anyOf": [ { "type": "string", "enum": [ "private_individual", "protest_group", "government_monitoring" ] }, { "type": "null" } ] } }, "required": [ "result", "target" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string" } }, "next_step": { "type": "string" } }, "required": [ "dry_run", "stream", "estimate", "plan", "screen", "warnings", "next_step" ], "additionalProperties": false }, "endpoint": { "example": "/v1/listening/streams", "type": "string" }, "platform": { "const": "listening", "type": "string" }, "request_id": { "type": "string" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data", "credits_used", "request_id" ], "type": "object" } } }, "description": "The dry run: the listener as it would be stored, its estimate, its plan and the screen's verdict. Free.", "headers": { "Server-Timing": { "description": "Time spent in each phase: `validate`, `compile`, `screen`, `estimate`, `render`.", "schema": { "type": "string" } }, "X-Credits-Used": { "schema": { "const": "0", "type": "string" } } } }, "400": { "description": "Invalid request - missing or malformed parameters", "x-error-codes": [ "INVALID_REQUEST", "COHORT_MEMBER_LIMIT_EXCEEDED", "COHORT_LIMIT_EXCEEDED", "COHORT_IDENTITY_PLATFORM_UNSUPPORTED" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "INVALID_REQUEST", "message": "Invalid request - missing or malformed parameters", "status": 400, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "x-error-codes": [ "MISSING_API_KEY", "INVALID_API_KEY" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "MISSING_API_KEY", "message": "Unauthorized - missing or invalid API key", "status": 401, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "413": { "description": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "x-error-codes": [ "PAYLOAD_TOO_LARGE", "COHORT_RESULT_TOO_LARGE" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "PAYLOAD_TOO_LARGE", "message": "Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling", "status": 413, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } }, "429": { "description": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "x-error-codes": [ "RATE_LIMITED", "CONCURRENCY_LIMIT" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "success": false, "error": { "type": "RATE_LIMITED", "message": "Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.", "status": 429, "doc_url": "https://www.socialcrawl.dev/docs/errors" }, "credits_used": 0, "credits_remaining": null, "request_id": "req-abc123" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "summary": "Price and validate a listener (dry run)", "tags": [ "listening" ], "x-credit-cost": 0 } } }, "x-full-spec": "https://www.socialcrawl.dev/v1/openapi.json" }