{
  "components": {
    "examples": {
      "forbidden": {
        "summary": "The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code.",
        "value": {
          "error": {
            "code": "forbidden",
            "message": "The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 403,
            "retryable": false,
            "param": null,
            "remediation": "Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#forbidden",
            "details": {},
            "charged": false
          }
        }
      },
      "idempotency_key_in_progress": {
        "summary": "A request with this Idempotency-Key is still running.",
        "value": {
          "error": {
            "code": "idempotency_key_in_progress",
            "message": "A request with this Idempotency-Key is still running.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 409,
            "retryable": true,
            "param": null,
            "remediation": "Retry after the number of seconds in the retry-after header to get that request's result.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#idempotency_key_in_progress",
            "details": {},
            "charged": false
          }
        }
      },
      "idempotency_key_reused": {
        "summary": "The Idempotency-Key was already used with a different request (another route, or another body).",
        "value": {
          "error": {
            "code": "idempotency_key_reused",
            "message": "The Idempotency-Key was already used with a different request (another route, or another body).",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 422,
            "retryable": false,
            "param": null,
            "remediation": "Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#idempotency_key_reused",
            "details": {},
            "charged": false
          }
        }
      },
      "insufficient_credits": {
        "summary": "The account does not have enough credits for this request.",
        "value": {
          "error": {
            "code": "insufficient_credits",
            "message": "The account does not have enough credits for this request.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 402,
            "retryable": false,
            "param": null,
            "remediation": "Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#insufficient_credits",
            "details": {},
            "charged": false
          }
        }
      },
      "internal": {
        "summary": "Unexpected SocialTap error.",
        "value": {
          "error": {
            "code": "internal",
            "message": "Unexpected SocialTap error.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 500,
            "retryable": true,
            "param": null,
            "remediation": "Retry with backoff; contact support with the request_id if it persists.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#internal",
            "details": {},
            "charged": false
          }
        }
      },
      "invalid_cursor": {
        "summary": "The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it.",
        "value": {
          "error": {
            "code": "invalid_cursor",
            "message": "The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 400,
            "retryable": false,
            "param": null,
            "remediation": "Repeat the original request without cursor to start the list again.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#invalid_cursor",
            "details": {},
            "charged": false
          }
        }
      },
      "invalid_input": {
        "summary": "The request parameters are missing or malformed, or the URL is not a supported link for this endpoint.",
        "value": {
          "error": {
            "code": "invalid_input",
            "message": "The request parameters are missing or malformed, or the URL is not a supported link for this endpoint.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 400,
            "retryable": false,
            "param": null,
            "remediation": "Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#invalid_input",
            "details": {},
            "charged": false
          }
        }
      },
      "job_not_found": {
        "summary": "No job with this ID exists for the account: unknown, or past its retention.",
        "value": {
          "error": {
            "code": "job_not_found",
            "message": "No job with this ID exists for the account: unknown, or past its retention.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 404,
            "retryable": false,
            "param": null,
            "remediation": "Check the job ID; finished jobs are kept for a limited time.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#job_not_found",
            "details": {},
            "charged": false
          }
        }
      },
      "no_transcript": {
        "summary": "The media exists but has no transcript: no caption track and no speech to transcribe.",
        "value": {
          "error": {
            "code": "no_transcript",
            "message": "The media exists but has no transcript: no caption track and no speech to transcribe.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 404,
            "retryable": false,
            "param": null,
            "remediation": "Do not retry; try another language with lang if the platform offers one.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#no_transcript",
            "details": {},
            "charged": false
          }
        }
      },
      "not_found": {
        "summary": "The item does not exist or was deleted.",
        "value": {
          "error": {
            "code": "not_found",
            "message": "The item does not exist or was deleted.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 404,
            "retryable": false,
            "param": null,
            "remediation": "Check the URL or ID; do not retry.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#not_found",
            "details": {},
            "charged": false
          }
        }
      },
      "overloaded": {
        "summary": "SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged.",
        "value": {
          "error": {
            "code": "overloaded",
            "message": "SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 503,
            "retryable": true,
            "param": null,
            "remediation": "Retry after the number of seconds in the retry-after header; failed requests are free.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#overloaded",
            "details": {},
            "charged": false
          }
        }
      },
      "private_or_unavailable": {
        "summary": "The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code.",
        "value": {
          "error": {
            "code": "private_or_unavailable",
            "message": "The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 403,
            "retryable": false,
            "param": null,
            "remediation": "Only public items can be fetched; do not retry.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#private_or_unavailable",
            "details": {},
            "charged": false
          }
        }
      },
      "rate_limited": {
        "summary": "The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead.",
        "value": {
          "error": {
            "code": "rate_limited",
            "message": "The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 429,
            "retryable": true,
            "param": null,
            "remediation": "Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#rate_limited",
            "details": {},
            "charged": false
          }
        }
      },
      "spend_limit_reached": {
        "summary": "The API key reached its spend limit for the current period; the account may still have credits.",
        "value": {
          "error": {
            "code": "spend_limit_reached",
            "message": "The API key reached its spend limit for the current period; the account may still have credits.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 402,
            "retryable": false,
            "param": null,
            "remediation": "Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#spend_limit_reached",
            "details": {},
            "charged": false
          }
        }
      },
      "unauthorized": {
        "summary": "The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired).",
        "value": {
          "error": {
            "code": "unauthorized",
            "message": "The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired).",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 401,
            "retryable": false,
            "param": null,
            "remediation": "Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#unauthorized",
            "details": {},
            "charged": false
          }
        }
      },
      "upstream_blocked": {
        "summary": "The platform refused every attempt.",
        "value": {
          "error": {
            "code": "upstream_blocked",
            "message": "The platform refused every attempt.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 503,
            "retryable": true,
            "param": null,
            "remediation": "Retry later with backoff; failed requests are free.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#upstream_blocked",
            "details": {},
            "charged": false
          }
        }
      },
      "upstream_error": {
        "summary": "The platform failed or returned something unexpected.",
        "value": {
          "error": {
            "code": "upstream_error",
            "message": "The platform failed or returned something unexpected.",
            "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
            "status": 502,
            "retryable": true,
            "param": null,
            "remediation": "Retry with backoff; failed requests are free.",
            "doc_url": "https://staging-fly.socialtap.dev/docs/errors/#upstream_error",
            "details": {},
            "charged": false
          }
        }
      }
    },
    "headers": {
      "age": {
        "description": "Seconds since the data was fetched (cache hits only).",
        "schema": {
          "type": "integer"
        }
      },
      "allow": {
        "description": "Methods the endpoint accepts (method_not_allowed only).",
        "schema": {
          "type": "string"
        }
      },
      "deprecation": {
        "description": "RFC 9745: the endpoint is deprecated, as of this date (@<unix seconds>; may be in the future). Also in meta.warnings.",
        "schema": {
          "type": "string"
        }
      },
      "idempotent-replayed": {
        "description": "true when the answer replays an earlier request with the same Idempotency-Key (it shows the resource's current state).",
        "schema": {
          "type": "boolean"
        }
      },
      "link": {
        "description": "RFC 8288 links: rel=\"next\" is the next page of a list (while page.has_more), the same request with cursor set; rel=\"deprecation\" is a deprecated endpoint's notice.",
        "schema": {
          "type": "string"
        }
      },
      "location": {
        "description": "On 202 answers: the job's URL (GET it, free, for its status).",
        "schema": {
          "type": "string"
        }
      },
      "preference-applied": {
        "description": "RFC 7240: respond-async when Prefer: respond-async turned the request into a job (202).",
        "schema": {
          "type": "string"
        }
      },
      "ratelimit": {
        "description": "What is left of the ceiling (IETF RateLimit field): \"account\";r=<requests that may be sent at once now>;t=<seconds until the bucket is full again>.",
        "schema": {
          "type": "string"
        }
      },
      "ratelimit-policy": {
        "description": "The account's runaway-protection ceiling as an IETF RateLimit-Policy field, as enforced: a token bucket of q requests (twice the ceiling in requests per second, at least 10) that refills in w seconds: \"account\";q=<requests>;w=<seconds>. Not a plan limit.",
        "schema": {
          "type": "string"
        }
      },
      "retry-after": {
        "description": "Seconds to wait before retrying; sent only with the codes whose retry_after is set in the error codes list (never on credit errors).",
        "schema": {
          "type": "integer"
        }
      },
      "sunset": {
        "description": "RFC 8594: when a deprecated endpoint stops answering (HTTP-date); from then on it answers endpoint_retired.",
        "schema": {
          "type": "string"
        }
      },
      "x-client-request-id": {
        "description": "Your x-client-request-id, echoed (also meta.client_request_id).",
        "schema": {
          "type": "string"
        }
      },
      "x-credits-charged": {
        "description": "Credits charged for this request (0 for errors and cache hits).",
        "schema": {
          "type": "integer"
        }
      },
      "x-credits-remaining": {
        "description": "Account balance after this request; for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance.",
        "schema": {
          "type": "integer"
        }
      },
      "x-request-id": {
        "description": "Unique request ID; include it when contacting support.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "AsyncAccepted": {
        "content": {
          "application/json": {
            "schema": {
              "properties": {
                "data": {
                  "properties": {
                    "cancel_requested_at": {
                      "format": "date-time",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "created_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "credits": {
                      "properties": {
                        "charged": {
                          "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                          "type": "integer"
                        },
                        "max": {
                          "description": "max_credits: the most the job may spend.",
                          "type": "integer"
                        },
                        "reserved": {
                          "description": "Credits its running pages may still use (0 once the job ends).",
                          "type": "integer"
                        }
                      },
                      "required": [
                        "max",
                        "reserved",
                        "charged"
                      ],
                      "type": "object"
                    },
                    "expires_at": {
                      "description": "The deadline: items not ended by then expire.",
                      "format": "date-time",
                      "type": "string"
                    },
                    "finished_at": {
                      "description": "When the job ended; null while it runs.",
                      "format": "date-time",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "id": {
                      "description": "The job ID (job_…).",
                      "type": "string"
                    },
                    "max_age": {
                      "description": "The job's max_age; null when it accepts no cached results.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "metadata": {
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "Your metadata; {} when none.",
                      "type": "object"
                    },
                    "object": {
                      "description": "Always job.",
                      "enum": [
                        "job"
                      ],
                      "type": "string"
                    },
                    "request_counts": {
                      "properties": {
                        "canceled": {
                          "type": "integer"
                        },
                        "expired": {
                          "type": "integer"
                        },
                        "failed": {
                          "type": "integer"
                        },
                        "queued": {
                          "description": "Not started.",
                          "type": "integer"
                        },
                        "running": {
                          "description": "Started (fetching, waiting for a retry or walking pages).",
                          "type": "integer"
                        },
                        "succeeded": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "total",
                        "queued",
                        "running",
                        "succeeded",
                        "failed",
                        "canceled",
                        "expired"
                      ],
                      "type": "object"
                    },
                    "results_expire_at": {
                      "description": "When results are deleted; null while the job runs.",
                      "format": "date-time",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "results_url": {
                      "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "results_url_expires_at": {
                      "format": "date-time",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "started_at": {
                      "description": "When the first item started; null before.",
                      "format": "date-time",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "status": {
                      "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.",
                      "enum": [
                        "queued",
                        "running",
                        "canceling",
                        "completed",
                        "canceled",
                        "expired"
                      ],
                      "type": "string"
                    },
                    "webhook_url": {
                      "description": "The job's own webhook URL; null when none.",
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "object",
                    "id",
                    "status",
                    "request_counts",
                    "credits",
                    "max_age",
                    "metadata",
                    "webhook_url",
                    "created_at",
                    "started_at",
                    "finished_at",
                    "cancel_requested_at",
                    "expires_at",
                    "results_url",
                    "results_url_expires_at",
                    "results_expire_at"
                  ],
                  "type": "object"
                },
                "meta": {
                  "properties": {
                    "client_request_id": {
                      "description": "Your x-client-request-id, echoed; null when you sent none.",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "credits_charged": {
                      "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                      "type": "integer"
                    },
                    "credits_remaining": {
                      "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "mode": {
                      "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                      "enum": [
                        "live",
                        "test"
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "request_id": {
                      "description": "Unique request ID; include it when contacting support.",
                      "type": "string"
                    },
                    "warnings": {
                      "description": "Things to act on that did not fail the request. [] when none.",
                      "items": {
                        "properties": {
                          "code": {
                            "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                            "type": "string"
                          },
                          "doc_url": {
                            "description": "Where to read more (the changelog entry, the endpoint's docs).",
                            "type": "string"
                          },
                          "fields": {
                            "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "message": {
                            "description": "What to do about it.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "code",
                          "message",
                          "doc_url"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "request_id",
                    "credits_charged",
                    "credits_remaining",
                    "client_request_id",
                    "mode",
                    "warnings"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "data",
                "meta"
              ],
              "type": "object"
            }
          }
        },
        "description": "Accepted (only with `prefer: respond-async`): the request runs as a one-request job (`custom_id` \"request\", the `jobs` scope); its result is the job's result, priced as this request.",
        "headers": {
          "location": {
            "$ref": "#/components/headers/location"
          },
          "preference-applied": {
            "$ref": "#/components/headers/preference-applied"
          },
          "x-credits-charged": {
            "$ref": "#/components/headers/x-credits-charged"
          },
          "x-credits-remaining": {
            "$ref": "#/components/headers/x-credits-remaining"
          },
          "x-request-id": {
            "$ref": "#/components/headers/x-request-id"
          }
        }
      }
    },
    "schemas": {
      "Ad": {
        "properties": {
          "advertiser": {
            "$ref": "#/components/schemas/ProfileRef",
            "description": "The advertising page, business or account."
          },
          "approximate_fields": {
            "description": "JSON paths of values that are rounded, date-only or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "audience_size": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Range"
              },
              {
                "type": "null"
              }
            ],
            "description": "Estimated target audience size range; null when not disclosed."
          },
          "country_codes": {
            "description": "ISO 3166-1 alpha-2 countries where it was shown; [] if not disclosed.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "creatives": {
            "description": "The ad's creatives: one per card of a carousel and per variation of a dynamic or catalog ad, else one for the ad itself; [] if none are shown.",
            "items": {
              "$ref": "#/components/schemas/AdCreative"
            },
            "type": "array"
          },
          "first_shown_at": {
            "description": "First delivery, RFC 3339 UTC (often date-only: see approximate_fields).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Library ad ID (string).",
            "type": "string"
          },
          "impressions": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Range"
              },
              {
                "type": "null"
              }
            ],
            "description": "Impressions or times shown range; null when not disclosed."
          },
          "is_active": {
            "description": "True while the ad is running.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_political": {
            "description": "Categorized as a political or social-issue ad; false when the library files it under another category, null when it shows none.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "languages": {
            "description": "BCP-47 languages of the ad; [] if not disclosed.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "last_shown_at": {
            "description": "Last delivery, RFC 3339 UTC; null while active.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "paid_by": {
            "description": "Disclosed payer (\"Paid for by\").",
            "type": [
              "string",
              "null"
            ]
          },
          "platform": {
            "description": "Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin).",
            "type": "string"
          },
          "platform_specific": {
            "$ref": "#/components/schemas/AdPlatformSpecific",
            "description": "Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown."
          },
          "publisher_platforms": {
            "description": "Where it ran, lowercase IDs (facebook, instagram, messenger, audience_network, youtube, …); [] if not disclosed.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "reach": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Range"
              },
              {
                "type": "null"
              }
            ],
            "description": "Unique users reached range; null when not disclosed."
          },
          "spend": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MoneyRange"
              },
              {
                "type": "null"
              }
            ],
            "description": "Spend range; null when not disclosed."
          },
          "type": {
            "description": "Creative shape. New values may be added; treat unknown values as other.",
            "enum": [
              "image",
              "video",
              "carousel",
              "text",
              "dynamic",
              "other"
            ],
            "type": "string"
          },
          "unknown_fields": {
            "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "description": "Public library page of the ad.",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "platform",
          "id",
          "url",
          "advertiser",
          "paid_by",
          "is_active",
          "first_shown_at",
          "last_shown_at",
          "type",
          "publisher_platforms",
          "creatives",
          "languages",
          "country_codes",
          "is_political",
          "impressions",
          "reach",
          "audience_size",
          "spend",
          "platform_specific",
          "approximate_fields",
          "unknown_fields"
        ],
        "type": "object"
      },
      "AdCreative": {
        "properties": {
          "body": {
            "description": "Primary text.",
            "type": [
              "string",
              "null"
            ]
          },
          "cta_text": {
            "description": "Call-to-action label (e.g. Shop now).",
            "type": [
              "string",
              "null"
            ]
          },
          "link_description": {
            "description": "Link description text.",
            "type": [
              "string",
              "null"
            ]
          },
          "link_url": {
            "description": "Destination URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "media": {
            "description": "Images and videos of this creative; [] if none.",
            "items": {
              "$ref": "#/components/schemas/Media"
            },
            "type": "array"
          },
          "title": {
            "description": "Headline.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "title",
          "body",
          "link_url",
          "link_description",
          "cta_text",
          "media"
        ],
        "type": "object"
      },
      "AdPlatformSpecific": {
        "type": "object"
      },
      "Comment": {
        "properties": {
          "approximate_fields": {
            "description": "JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "author": {
            "$ref": "#/components/schemas/ProfileRef",
            "description": "The commenting account."
          },
          "edited_at": {
            "description": "When the comment was last edited, RFC 3339 UTC; null when never edited or when the platform marks edits without a time (see is_edited).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Platform-native comment ID (string; Reddit without t1_).",
            "type": "string"
          },
          "is_by_post_author": {
            "description": "Written by the post's author (the creator's own comment, marked as such by the platform).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_edited": {
            "description": "The comment was edited after posting (the platform's edited mark); null when the platform does not say.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_liked_by_author": {
            "description": "Liked or hearted by the post's author.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_pinned": {
            "description": "Pinned by the post's author.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "metrics": {
            "$ref": "#/components/schemas/CommentMetrics",
            "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero."
          },
          "parent_id": {
            "description": "ID of the comment this replies to; null for top-level comments.",
            "type": [
              "string",
              "null"
            ]
          },
          "platform": {
            "description": "Platform ID (tiktok, youtube, …).",
            "type": "string"
          },
          "platform_specific": {
            "$ref": "#/components/schemas/CommentPlatformSpecific",
            "description": "Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown."
          },
          "post_id": {
            "description": "ID of the post commented on (equals post.id).",
            "type": "string"
          },
          "published_at": {
            "description": "When the comment was posted, RFC 3339 UTC. Where the platform shows only a relative time (\"3 weeks ago\"), the latest time that label allows (the fetch time minus the stated amount), listed in approximate_fields.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "text": {
            "description": "Comment body as plain text.",
            "type": "string"
          },
          "unknown_fields": {
            "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "description": "Permalink, when the platform has one.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "platform",
          "id",
          "post_id",
          "parent_id",
          "url",
          "text",
          "author",
          "published_at",
          "edited_at",
          "is_edited",
          "is_pinned",
          "is_liked_by_author",
          "is_by_post_author",
          "metrics",
          "platform_specific",
          "approximate_fields",
          "unknown_fields"
        ],
        "type": "object"
      },
      "CommentMetrics": {
        "properties": {
          "like_count": {
            "description": "Likes or upvotes; never negative.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "reply_count": {
            "description": "Direct replies.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "like_count",
          "reply_count"
        ],
        "type": "object"
      },
      "CommentPlatformSpecific": {
        "properties": {
          "rumble": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RumbleCommentSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "Rumble's own comment fields."
          },
          "tiktok": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TikTokCommentSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "TikTok's own comment fields."
          }
        },
        "type": "object"
      },
      "ErrorBody": {
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ErrorDetail": {
        "properties": {
          "charged": {
            "description": "Whether the request was charged: always false, failed requests are free.",
            "type": "boolean"
          },
          "code": {
            "description": "Machine-readable error code (see the error codes list); stable.",
            "enum": [
              "invalid_input",
              "invalid_cursor",
              "unauthorized",
              "forbidden",
              "insufficient_credits",
              "spend_limit_reached",
              "rate_limited",
              "method_not_allowed",
              "endpoint_retired",
              "idempotency_key_reused",
              "idempotency_key_in_progress",
              "job_not_found",
              "unknown_endpoint",
              "not_found",
              "private_or_unavailable",
              "no_transcript",
              "upstream_blocked",
              "upstream_error",
              "overloaded",
              "internal"
            ],
            "type": "string"
          },
          "details": {
            "description": "The code's dynamic values (the error codes list documents each code's keys); {} when none.",
            "type": "object"
          },
          "doc_url": {
            "description": "URL of this code's documentation.",
            "type": "string"
          },
          "message": {
            "description": "What went wrong and how to fix it, for humans and agents; wording may change.",
            "type": "string"
          },
          "param": {
            "description": "The query parameter or header the error is about; null when it is not about one input.",
            "type": [
              "string",
              "null"
            ]
          },
          "remediation": {
            "description": "What to do about this code, one sentence.",
            "type": "string"
          },
          "request_id": {
            "description": "Unique request ID; include it when contacting support.",
            "type": "string"
          },
          "retryable": {
            "description": "True when repeating the same request later may succeed (after details.retry_after when present).",
            "type": "boolean"
          },
          "status": {
            "description": "The HTTP status of the response, repeated for clients that only see the body.",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "code",
          "message",
          "request_id",
          "status",
          "retryable",
          "param",
          "remediation",
          "doc_url",
          "details",
          "charged"
        ],
        "type": "object"
      },
      "FacebookLink": {
        "properties": {
          "image_url": {
            "description": "The card's image.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "description": "The card's headline.",
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "The linked page, as the author shared it (Facebook's l.facebook.com redirect removed).",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "url",
          "title",
          "image_url"
        ],
        "type": "object"
      },
      "FacebookPostResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Post"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "FacebookPostSpecific": {
        "properties": {
          "feedback_id": {
            "description": "Facebook's feedback ID of the post: the thread its comments and reactions hang on.",
            "type": [
              "string",
              "null"
            ]
          },
          "link": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FacebookLink"
              },
              {
                "type": "null"
              }
            ],
            "description": "The link card a post shares (an article, a site); null when none."
          },
          "reactions": {
            "description": "Reactions by type, most first, as Facebook lists them under the post; [] when none.",
            "items": {
              "$ref": "#/components/schemas/FacebookReaction"
            },
            "type": "array"
          },
          "shared_post": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FacebookSharedPost"
              },
              {
                "type": "null"
              }
            ],
            "description": "The post this one reshares; null when it is not a reshare."
          },
          "video_id": {
            "description": "The video's ID (facebook.com/reel/<video_id>) on a video or reel post; null on other posts.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "feedback_id",
          "video_id",
          "reactions",
          "shared_post",
          "link"
        ],
        "type": "object"
      },
      "FacebookReaction": {
        "properties": {
          "count": {
            "description": "How many people reacted with it.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "type": {
            "description": "Reaction type. New values may be added.",
            "enum": [
              "like",
              "love",
              "care",
              "haha",
              "wow",
              "sad",
              "angry"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "count"
        ],
        "type": "object"
      },
      "FacebookSearch_adsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 10), most impressions first.",
            "items": {
              "$ref": "#/components/schemas/Ad"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "FacebookSharedPost": {
        "properties": {
          "author": {
            "$ref": "#/components/schemas/ProfileRef",
            "description": "Its author."
          },
          "id": {
            "description": "Its post ID.",
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "Its URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "url",
          "author"
        ],
        "type": "object"
      },
      "FacebookTranscriptResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Transcript"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "InputRef": {
        "properties": {
          "id": {
            "description": "Platform-native ID of the item; null when it is only known after the fetch and the request failed.",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "description": "What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.",
            "type": "string"
          },
          "url": {
            "description": "Canonical URL of the item; null when unknown.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "kind",
          "id",
          "url"
        ],
        "type": "object"
      },
      "InstagramPostResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Post"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "InstagramPostSpecific": {
        "properties": {
          "is_ai_generated": {
            "description": "Instagram shows its AI label (made or edited with AI); false when it shows none.",
            "type": [
              "boolean",
              "null"
            ]
          }
        },
        "required": [
          "is_ai_generated"
        ],
        "type": "object"
      },
      "InstagramPostsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 12), newest first.",
            "items": {
              "$ref": "#/components/schemas/Post"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "InstagramProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Profile"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "InstagramProfileSpecific": {
        "properties": {
          "fbid": {
            "description": "The account's Meta-wide ID (17841…), the one Meta's Instagram Graph API uses; id is Instagram's own user ID. Null when the source does not show it.",
            "type": [
              "string",
              "null"
            ]
          },
          "is_highlights_shown": {
            "description": "True when the profile shows story highlights, false when it shows none; null when unknown (private accounts, or a source that does not show them).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_memorialized": {
            "description": "True when Instagram has memorialized the account (its owner has died), false otherwise; null when unknown.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_story_live": {
            "description": "True when the account has a story up now (stories last 24 hours), false when it has none; null when unknown (Instagram does not say for private accounts).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "pronouns": {
            "description": "The pronouns the owner chose to show on the profile, as shown; [] when none (listed in unknown_fields when the source cannot see them).",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "fbid",
          "is_memorialized",
          "is_story_live",
          "is_highlights_shown",
          "pronouns"
        ],
        "type": "object"
      },
      "InstagramTranscriptResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Transcript"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "Link": {
        "properties": {
          "title": {
            "description": "Link label shown by the platform.",
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "Link target, absolute (https:// is added where the platform stores the link without a scheme).",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "title"
        ],
        "type": "object"
      },
      "Media": {
        "properties": {
          "alt_text": {
            "description": "Accessibility text provided by the author or platform.",
            "type": [
              "string",
              "null"
            ]
          },
          "duration_ms": {
            "description": "Duration in milliseconds (video and audio only).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "expires_at": {
            "description": "When url stops working, RFC 3339 UTC, read from the platform's signed URL; null when unknown or when it does not expire.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "height": {
            "description": "Height in pixels.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "thumbnail_url": {
            "description": "Poster or preview image URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "description": "Kind of file. New values may be added; treat unknown values as other.",
            "enum": [
              "image",
              "video",
              "audio",
              "gif"
            ],
            "type": "string"
          },
          "url": {
            "description": "Direct file URL; null when the platform withholds it, or when the link would only work from SocialTap's network or with a login. Often signed and expiring: see expires_at.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "width": {
            "description": "Width in pixels.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "type",
          "url",
          "expires_at",
          "thumbnail_url",
          "width",
          "height",
          "duration_ms",
          "alt_text"
        ],
        "type": "object"
      },
      "MoneyRange": {
        "properties": {
          "currency": {
            "description": "ISO 4217 currency code, uppercase (USD).",
            "type": "string"
          },
          "lower_bound": {
            "description": "Inclusive lower bound, in whole units of currency.",
            "format": "int64",
            "type": "integer"
          },
          "upper_bound": {
            "description": "Inclusive upper bound in whole units of currency; null when open-ended.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "lower_bound",
          "upper_bound",
          "currency"
        ],
        "type": "object"
      },
      "PageInfo": {
        "properties": {
          "end_reason": {
            "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
            "enum": [
              "end",
              "platform_limit",
              "max_pages",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
            "type": [
              "string",
              "null"
            ]
          },
          "next_cursor_expires_at": {
            "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "has_more",
          "next_cursor",
          "next_cursor_expires_at",
          "end_reason"
        ],
        "type": "object"
      },
      "Post": {
        "properties": {
          "approximate_fields": {
            "description": "JSON paths of values rounded by the platform or parsed from display text. A list path (external_links) means the list may be incomplete. [] when all exact.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "author": {
            "$ref": "#/components/schemas/ProfileRef",
            "description": "The posting account."
          },
          "coauthors": {
            "description": "Other accounts credited as co-authors of the post (Instagram and Facebook collabs, YouTube collaborations), in the platform's order, author excluded; [] if none.",
            "items": {
              "$ref": "#/components/schemas/ProfileRef"
            },
            "type": "array"
          },
          "duration_ms": {
            "description": "Length of the primary video or audio in milliseconds; null for other posts.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "hashtags": {
            "description": "Hashtags without #, case kept; [] if none.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "id": {
            "description": "Platform-native post ID (string; Instagram shortcode, Reddit without t3_).",
            "type": "string"
          },
          "is_nsfw": {
            "description": "Marked adult or sensitive by the platform.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_pinned": {
            "description": "Pinned to the author's profile.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_sponsored": {
            "description": "Labeled as a paid partnership or branded content.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "language": {
            "description": "BCP-47 language of text, when the platform states it.",
            "type": [
              "string",
              "null"
            ]
          },
          "media": {
            "description": "Attachments in display order (carousel items); [] for text posts.",
            "items": {
              "$ref": "#/components/schemas/Media"
            },
            "type": "array"
          },
          "mentions": {
            "description": "Mentioned or tagged usernames without @; [] if none.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "metrics": {
            "$ref": "#/components/schemas/PostMetrics",
            "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero."
          },
          "platform": {
            "description": "Platform ID (tiktok, youtube, …).",
            "type": "string"
          },
          "platform_specific": {
            "$ref": "#/components/schemas/PostPlatformSpecific",
            "description": "Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown."
          },
          "platform_type": {
            "description": "The platform's own product label, lowercase (reel, short, story, live, tweet, …).",
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "description": "When the post went public, RFC 3339 UTC.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "text": {
            "description": "Caption, description or body as plain text.",
            "type": [
              "string",
              "null"
            ]
          },
          "thumbnail_url": {
            "description": "Cover or poster image URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "description": "Headline (YouTube title, Reddit title); null on caption-only platforms.",
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "description": "Normalized content shape. New values may be added; treat unknown values as other.",
            "enum": [
              "video",
              "image",
              "carousel",
              "text",
              "link",
              "audio"
            ],
            "type": "string"
          },
          "unknown_fields": {
            "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "description": "Canonical post URL.",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "platform",
          "id",
          "url",
          "type",
          "platform_type",
          "title",
          "text",
          "language",
          "published_at",
          "author",
          "coauthors",
          "duration_ms",
          "thumbnail_url",
          "media",
          "hashtags",
          "mentions",
          "is_pinned",
          "is_sponsored",
          "is_nsfw",
          "metrics",
          "platform_specific",
          "approximate_fields",
          "unknown_fields"
        ],
        "type": "object"
      },
      "PostMetrics": {
        "properties": {
          "comment_count": {
            "description": "Comments and replies.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "like_count": {
            "description": "Likes, hearts, total reactions or upvotes; never negative. Null when hidden by the owner.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "quote_count": {
            "description": "Quote posts.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "repost_count": {
            "description": "Reposts, retweets or reshares.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "save_count": {
            "description": "Saves, bookmarks or favorites.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "share_count": {
            "description": "Shares or sends (not reposts).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "view_count": {
            "description": "Views or plays.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "view_count",
          "like_count",
          "comment_count",
          "share_count",
          "repost_count",
          "quote_count",
          "save_count"
        ],
        "type": "object"
      },
      "PostPlatformSpecific": {
        "properties": {
          "facebook": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FacebookPostSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A Facebook post's own fields."
          },
          "instagram": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/InstagramPostSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "An Instagram post's own fields (core/post_instagram.go)."
          },
          "rumble": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RumblePostSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A Rumble video's own fields."
          },
          "tiktok": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TikTokPostSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A TikTok post's own fields."
          },
          "youtube": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/YouTubePostSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A YouTube video's own fields."
          }
        },
        "type": "object"
      },
      "Profile": {
        "properties": {
          "approximate_fields": {
            "description": "JSON paths of values rounded by the platform or parsed from display text (e.g. metrics.follower_count). A list path (external_links) means the list may be incomplete. [] when all exact.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "avatar_url": {
            "description": "Profile picture URL (largest available). Platform CDN URLs can expire within hours.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "banner_url": {
            "description": "Header or cover image URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "bio": {
            "description": "Profile bio, channel description or page about text; null when empty or not exposed.",
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "description": "Platform category label (e.g. Musician, Media & Entertainment), as shown; not normalized. Often set only for business or creator accounts.",
            "type": [
              "string",
              "null"
            ]
          },
          "country_code": {
            "description": "ISO 3166-1 alpha-2 country the platform states for the account.",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "Account creation or join date, RFC 3339 UTC (some platforms give only the day: see approximate_fields).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "display_name": {
            "description": "Display name, channel title or page name; null when empty or not exposed.",
            "type": [
              "string",
              "null"
            ]
          },
          "external_links": {
            "description": "Links in the bio or channel links; [] if none or not exposed.",
            "items": {
              "$ref": "#/components/schemas/Link"
            },
            "type": "array"
          },
          "id": {
            "description": "Platform-native account ID (string; YouTube UC…, Reddit without t2_).",
            "type": "string"
          },
          "is_private": {
            "description": "True when the account's posts are not public.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_verified": {
            "description": "Platform verification badge; null where the platform has no badge.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "location": {
            "description": "Self-declared location text.",
            "type": [
              "string",
              "null"
            ]
          },
          "metrics": {
            "$ref": "#/components/schemas/ProfileMetrics",
            "description": "Counts at fetch time; null = hidden or not exposed, 0 = zero."
          },
          "platform": {
            "description": "Platform ID (tiktok, youtube, …).",
            "type": "string"
          },
          "platform_specific": {
            "$ref": "#/components/schemas/ProfilePlatformSpecific",
            "description": "Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown."
          },
          "type": {
            "description": "Coarse account kind, as the platform labels it; unknown when it does not (TikTok labels organizations only). New values may be added; treat unknown values as unknown.",
            "enum": [
              "person",
              "organization",
              "community",
              "unknown"
            ],
            "type": "string"
          },
          "unknown_fields": {
            "description": "JSON paths of lists whose [] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. [] when every list is known.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "description": "Canonical profile URL.",
            "format": "uri",
            "type": "string"
          },
          "username": {
            "description": "Handle without the @; null when the account has none.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "platform",
          "id",
          "username",
          "display_name",
          "url",
          "type",
          "bio",
          "avatar_url",
          "banner_url",
          "is_verified",
          "is_private",
          "category",
          "external_links",
          "location",
          "country_code",
          "created_at",
          "metrics",
          "platform_specific",
          "approximate_fields",
          "unknown_fields"
        ],
        "type": "object"
      },
      "ProfileMetrics": {
        "properties": {
          "follower_count": {
            "description": "Followers or subscribers.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "following_count": {
            "description": "Accounts this profile follows.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "post_count": {
            "description": "Posts or videos as the platform counts them on the profile (for a private account, posts the caller cannot see).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "total_like_count": {
            "description": "Likes received across all of the profile's posts (not likes given).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "total_view_count": {
            "description": "Lifetime views across all of the profile's posts.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "follower_count",
          "following_count",
          "post_count",
          "total_like_count",
          "total_view_count"
        ],
        "type": "object"
      },
      "ProfilePlatformSpecific": {
        "properties": {
          "instagram": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/InstagramProfileSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "An Instagram account's own fields (core/profile_instagram.go)."
          },
          "rumble": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RumbleProfileSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A Rumble channel's or user's own fields (core/profile_rumble.go)."
          },
          "threads": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ThreadsProfileSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A Threads account's own fields (core/profile_threads.go)."
          },
          "youtube": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/YouTubeProfileSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A YouTube channel's own fields (core/profile_youtube.go)."
          }
        },
        "type": "object"
      },
      "ProfileRef": {
        "properties": {
          "avatar_url": {
            "description": "Profile picture URL. Platform CDN URLs can expire within hours.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "display_name": {
            "description": "Display name shown on the profile.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Platform-native account ID; null when only the handle is known.",
            "type": [
              "string",
              "null"
            ]
          },
          "is_verified": {
            "description": "Platform verification badge; null where the platform has no badge.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "url": {
            "description": "Canonical profile URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "username": {
            "description": "Handle without the @; null when the account has none.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "username",
          "display_name",
          "url",
          "avatar_url",
          "is_verified"
        ],
        "type": "object"
      },
      "Range": {
        "properties": {
          "lower_bound": {
            "description": "Inclusive lower bound.",
            "format": "int64",
            "type": "integer"
          },
          "upper_bound": {
            "description": "Inclusive upper bound; null when open-ended (e.g. \">1M\"). Equal to lower_bound when exact.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "lower_bound",
          "upper_bound"
        ],
        "type": "object"
      },
      "ResponseMeta": {
        "properties": {
          "client_request_id": {
            "description": "Your x-client-request-id, echoed; null when you sent none.",
            "type": [
              "string",
              "null"
            ]
          },
          "credits_charged": {
            "description": "Credits charged for this request (0 for errors and cache hits).",
            "format": "int64",
            "type": "integer"
          },
          "credits_remaining": {
            "description": "Account balance after this request (the x-credits-remaining header); for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance; null when SocialTap could not read it.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "fetched_at": {
            "description": "When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).",
            "format": "date-time",
            "type": "string"
          },
          "input": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/InputRef"
              },
              {
                "type": "null"
              }
            ],
            "description": "What the request's url or handle resolved to: kind, platform ID and canonical URL, so you can confirm what was fetched; null for searches."
          },
          "is_cached": {
            "description": "True when served from the cache (free); see max_age.",
            "type": "boolean"
          },
          "latency_ms": {
            "description": "Time SocialTap spent on the request, in milliseconds.",
            "format": "int64",
            "type": "integer"
          },
          "mode": {
            "description": "live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added.",
            "enum": [
              "live",
              "test",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "platform": {
            "description": "Platform ID of the endpoint (youtube, tiktok, …).",
            "examples": [
              "youtube"
            ],
            "type": "string"
          },
          "request_id": {
            "description": "Unique request ID; include it when contacting support.",
            "type": "string"
          },
          "source": {
            "description": "Which upstream strategy produced the data.",
            "examples": [
              "captions"
            ],
            "type": "string"
          },
          "warnings": {
            "description": "Things to act on that did not fail the request: a deprecated endpoint, partial data. [] when none.",
            "items": {
              "$ref": "#/components/schemas/Warning"
            },
            "type": "array"
          }
        },
        "required": [
          "request_id",
          "platform",
          "source",
          "is_cached",
          "credits_charged",
          "latency_ms",
          "fetched_at",
          "input",
          "credits_remaining",
          "client_request_id",
          "warnings",
          "mode"
        ],
        "type": "object"
      },
      "RumbleCaptionTrack": {
        "properties": {
          "is_auto_generated": {
            "description": "Generated by Rumble's speech recognition.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "label": {
            "description": "Rumble's label (\"English (auto)\").",
            "type": [
              "string",
              "null"
            ]
          },
          "language": {
            "description": "Language code (en, es, …).",
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "WebVTT file URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "language",
          "label",
          "url",
          "is_auto_generated"
        ],
        "type": "object"
      },
      "RumbleCommentSpecific": {
        "properties": {
          "author_badges": {
            "description": "The badges Rumble shows beside the commenter's name, by their label as Rumble writes it (seen: Verified, Admin, Moderator, Supporter, Supporter+, Supporter++, Sub, Locals Supporter; new labels may appear). [] when none.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "dislike_count": {
            "description": "Thumbs-down votes on the comment. Exact below 1,000; from 1,000 Rumble shows a label such as \"1.31K\", taken to be cut to three significant digits as Rumble's other counts are (not checked against an exact count), and listed in approximate_fields.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "dislike_count",
          "author_badges"
        ],
        "type": "object"
      },
      "RumbleCommentsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 500), newest first with sort=newest, Rumble's Sort by likes order of comments, each followed by its replies with sort=popular.",
            "items": {
              "$ref": "#/components/schemas/Comment"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "RumbleFile": {
        "properties": {
          "bitrate_kbps": {
            "description": "Bitrate in kbit/s.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "format": {
            "description": "mp4 or webm file, hls playlist (all qualities), tar (one HLS quality packed in one file; url is its playlist) or aac audio. New values may be added.",
            "enum": [
              "mp4",
              "webm",
              "hls",
              "tar",
              "aac",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "height": {
            "description": "Height in pixels; null for audio and playlists.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "kind": {
            "description": "video (picture and sound), audio (sound only) or preview (the seek bar's low-resolution video, no sound). New values may be added.",
            "enum": [
              "video",
              "audio",
              "preview",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "size_bytes": {
            "description": "File size in bytes; null when Rumble does not state it.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "url": {
            "description": "File or playlist URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "width": {
            "description": "Width in pixels; null for audio and playlists.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "kind",
          "format",
          "url",
          "width",
          "height",
          "bitrate_kbps",
          "size_bytes"
        ],
        "type": "object"
      },
      "RumblePostResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Post"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "RumblePostSpecific": {
        "properties": {
          "author_follower_count": {
            "description": "The channel's or user's follower count. Exact in Rumble's JSON (shorts, lists); a video's page cuts it to three significant digits (in approximate_fields).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "caption_tracks": {
            "description": "Caption tracks (WebVTT); [] when none.",
            "items": {
              "$ref": "#/components/schemas/RumbleCaptionTrack"
            },
            "type": "array"
          },
          "category": {
            "description": "Rumble's primary category (News, Podcasts, …).",
            "type": [
              "string",
              "null"
            ]
          },
          "concurrent_viewer_count": {
            "description": "Viewers watching a live stream now; null when not live.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "dislike_count": {
            "description": "Thumbs-down votes. Exact in Rumble's JSON (shorts, grid lists); a video's page and the older HTML cards cut it to three significant digits from 1,000 (in approximate_fields).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "embed_id": {
            "description": "The video's embed player ID (rumble.com/embed/<embed_id>/): its own namespace, not id.",
            "type": [
              "string",
              "null"
            ]
          },
          "embed_url": {
            "description": "The embeddable player URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "files": {
            "description": "Every file and stream Rumble's player offers, largest video first; [] when none.",
            "items": {
              "$ref": "#/components/schemas/RumbleFile"
            },
            "type": "array"
          },
          "is_age_restricted": {
            "description": "Viewers must confirm their age to watch; null when the source does not show it.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_live_now": {
            "description": "A live stream on air now.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "keywords": {
            "description": "The uploader's tags; [] when none.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "live_started_at": {
            "description": "When a live stream went on air; null if never live.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "numeric_id": {
            "description": "Rumble's numeric video ID, which its own services use.",
            "type": [
              "string",
              "null"
            ]
          },
          "scheduled_start_at": {
            "description": "When a scheduled live stream is due to start; null otherwise.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "secondary_category": {
            "description": "Rumble's secondary category; null when none.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "embed_id",
          "embed_url",
          "numeric_id",
          "dislike_count",
          "category",
          "secondary_category",
          "keywords",
          "caption_tracks",
          "files",
          "is_live_now",
          "live_started_at",
          "scheduled_start_at",
          "concurrent_viewer_count",
          "is_age_restricted",
          "author_follower_count"
        ],
        "type": "object"
      },
      "RumblePostsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 25), Rumble's upload order (newest uploads first, not strictly by published_at) with sort=newest, Rumble's View count order (most viewed first) with sort=popular.",
            "items": {
              "$ref": "#/components/schemas/Post"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "RumbleProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Profile"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "RumbleProfileSpecific": {
        "properties": {
          "account_type": {
            "description": "channel for a Rumble channel (rumble.com/c/<name>), user for a Rumble user (rumble.com/user/<name>: the account that uploads, which can own channels). Null when unknown. New values may be added; treat unknown values as unknown.",
            "enum": [
              "channel",
              "user",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "numeric_id": {
            "description": "Rumble's numeric ID of the channel or the user, in decimal (the channel's is the number in its rumble.com/c/c-<id> link). Channels and users are numbered separately, so the same number can name a channel and a user: id is the unambiguous reference. Null when unknown.",
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "description": "The id of the Rumble user that owns the channel (_u…, the id this endpoint answers for that user); for a user, its own id. Channels of one owner share it. Null when the page does not show it.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "account_type",
          "numeric_id",
          "user_id"
        ],
        "type": "object"
      },
      "RumbleSearch_postsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 36), newest first with sort=newest, Rumble's View count order (most viewed first) with sort=popular, Rumble's relevance order with sort=relevance.",
            "items": {
              "$ref": "#/components/schemas/Post"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "RumbleTranscriptResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Transcript"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "RumbleTranscriptSpecific": {
        "properties": {
          "caption_tracks": {
            "description": "Every caption track Rumble offers for the video (WebVTT); [] when none.",
            "items": {
              "$ref": "#/components/schemas/RumbleCaptionTrack"
            },
            "type": "array"
          },
          "caption_url": {
            "description": "The WebVTT file of the caption track used; null for speech-to-text.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "track_label": {
            "description": "Rumble's label of the caption track used (\"English (auto)\"); null for speech-to-text.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "track_label",
          "caption_url",
          "caption_tracks"
        ],
        "type": "object"
      },
      "Segment": {
        "properties": {
          "end_ms": {
            "description": "End time in milliseconds from the beginning of the media.",
            "format": "int64",
            "type": "integer"
          },
          "start_ms": {
            "description": "Start time in milliseconds from the beginning of the media.",
            "format": "int64",
            "type": "integer"
          },
          "text": {
            "description": "Cue text, whitespace-normalized.",
            "type": "string"
          }
        },
        "required": [
          "start_ms",
          "end_ms",
          "text"
        ],
        "type": "object"
      },
      "ThreadsProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Profile"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "ThreadsProfileSpecific": {
        "properties": {
          "interest_tags": {
            "description": "Topic labels Threads shows on the profile, as shown; [] when it shows none (listed in unknown_fields when the source cannot see them).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "verified_link_urls": {
            "description": "The external_links URLs Threads marks as verified, in the same form; [] when none is marked (listed in unknown_fields when the source cannot see the links).",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "interest_tags",
          "verified_link_urls"
        ],
        "type": "object"
      },
      "TikTokCommentSpecific": {
        "properties": {
          "language": {
            "description": "The comment's language as TikTok detected it, an ISO 639-1 code (en, fr); null when TikTok could not tell (emoji, a name) or does not say.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "language"
        ],
        "type": "object"
      },
      "TikTokPostLocation": {
        "properties": {
          "address": {
            "description": "Address line.",
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "description": "Top-level place category.",
            "type": [
              "string",
              "null"
            ]
          },
          "city": {
            "description": "City.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Place ID.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Place name.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "address",
          "city",
          "category"
        ],
        "type": "object"
      },
      "TikTokPostMusic": {
        "properties": {
          "author_name": {
            "description": "Who TikTok credits for the sound.",
            "type": [
              "string",
              "null"
            ]
          },
          "cover_url": {
            "description": "Sound cover image URL.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "duration_ms": {
            "description": "Sound length in milliseconds.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "id": {
            "description": "Sound ID.",
            "type": [
              "string",
              "null"
            ]
          },
          "is_original": {
            "description": "An original sound a creator uploaded (false: a catalogue track).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "play_url": {
            "description": "Audio file URL, signed and expiring.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "description": "Sound title.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "author_name",
          "is_original",
          "duration_ms",
          "cover_url",
          "play_url"
        ],
        "type": "object"
      },
      "TikTokPostSpecific": {
        "properties": {
          "author_sec_uid": {
            "description": "The author's secUid, TikTok's account key that survives a rename.",
            "type": [
              "string",
              "null"
            ]
          },
          "country_code": {
            "description": "ISO 3166-1 alpha-2 country TikTok registers the post to (not the viewer's).",
            "type": [
              "string",
              "null"
            ]
          },
          "is_ad": {
            "description": "The post runs as a TikTok ad.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_ai_generated": {
            "description": "TikTok labels the post AI-generated.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "location": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TikTokPostLocation"
              },
              {
                "type": "null"
              }
            ],
            "description": "The tagged place; null when none."
          },
          "music": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TikTokPostMusic"
              },
              {
                "type": "null"
              }
            ],
            "description": "The post's sound."
          }
        },
        "required": [
          "author_sec_uid",
          "country_code",
          "is_ad",
          "is_ai_generated",
          "location",
          "music"
        ],
        "type": "object"
      },
      "TiktokCommentsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 50), TikTok's comment ranking (the order its app shows).",
            "items": {
              "$ref": "#/components/schemas/Comment"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "TiktokPostResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Post"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "TiktokPostsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 15), newest first.",
            "items": {
              "$ref": "#/components/schemas/Post"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "TiktokProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Profile"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "TiktokTranscriptResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Transcript"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "Transcript": {
        "properties": {
          "available_languages": {
            "description": "BCP-47 caption languages the platform offers for this post; [] if none or not listed.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "duration_ms": {
            "description": "Media duration in milliseconds; null when unknown.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "id": {
            "description": "Platform-native ID of the post (equals post.id).",
            "type": "string"
          },
          "is_auto_generated": {
            "description": "True when the track was machine-generated (platform auto-captions or ASR).",
            "type": "boolean"
          },
          "language": {
            "description": "BCP-47 language of the returned transcript; null when unknown.",
            "examples": [
              "en"
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "platform": {
            "description": "Platform the media is hosted on.",
            "examples": [
              "youtube"
            ],
            "type": "string"
          },
          "platform_specific": {
            "$ref": "#/components/schemas/TranscriptPlatformSpecific",
            "description": "Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown."
          },
          "segments": {
            "description": "Timed cues in order; never empty on success.",
            "items": {
              "$ref": "#/components/schemas/Segment"
            },
            "type": "array"
          },
          "source": {
            "description": "captions = platform caption track; asr = speech-to-text on the audio. New values may be added.",
            "enum": [
              "captions",
              "asr"
            ],
            "type": "string"
          },
          "text": {
            "description": "Full transcript: segment texts joined with single spaces.",
            "type": "string"
          },
          "url": {
            "description": "Canonical URL of the post.",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "platform",
          "id",
          "url",
          "language",
          "source",
          "is_auto_generated",
          "available_languages",
          "duration_ms",
          "segments",
          "text",
          "platform_specific"
        ],
        "type": "object"
      },
      "TranscriptPlatformSpecific": {
        "properties": {
          "rumble": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RumbleTranscriptSpecific"
              },
              {
                "type": "null"
              }
            ],
            "description": "A Rumble transcript's own fields."
          }
        },
        "type": "object"
      },
      "Warning": {
        "properties": {
          "code": {
            "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
            "type": "string"
          },
          "doc_url": {
            "description": "Where to read more (the changelog entry, the endpoint's docs).",
            "type": "string"
          },
          "fields": {
            "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "message": {
            "description": "What to do about it.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message",
          "doc_url"
        ],
        "type": "object"
      },
      "YouTubeChapter": {
        "properties": {
          "start_ms": {
            "description": "Start, in ms from the beginning.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "title": {
            "description": "Chapter title.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "title",
          "start_ms"
        ],
        "type": "object"
      },
      "YouTubePostSpecific": {
        "properties": {
          "author_subscriber_count": {
            "description": "The channel's subscriber count, rounded by YouTube (in approximate_fields); null when hidden.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "category": {
            "description": "YouTube category (Music, Gaming, …), in English.",
            "type": [
              "string",
              "null"
            ]
          },
          "chapters": {
            "description": "Chapters in playback order; [] when none.",
            "items": {
              "$ref": "#/components/schemas/YouTubeChapter"
            },
            "type": "array"
          },
          "description_links": {
            "description": "Links in the description, in order, deduplicated; [] when none.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "is_age_restricted": {
            "description": "Viewers must sign in to confirm their age; null when the answer does not tell.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_live_now": {
            "description": "A live stream on air now.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_paywalled": {
            "description": "Must be bought or rented (movies, paid content).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_unlisted": {
            "description": "Unlisted: watchable by link, not listed on the channel or in search.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "keywords": {
            "description": "The uploader's tags; [] when none.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "live_ended_at": {
            "description": "When a live stream or premiere ended; null while live or if never live.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "live_started_at": {
            "description": "When a live stream or premiere went on air; null if never live.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "scheduled_start_at": {
            "description": "When a scheduled stream or premiere is due to start; null otherwise.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "category",
          "keywords",
          "chapters",
          "description_links",
          "is_unlisted",
          "is_age_restricted",
          "is_paywalled",
          "is_live_now",
          "live_started_at",
          "live_ended_at",
          "scheduled_start_at",
          "author_subscriber_count"
        ],
        "type": "object"
      },
      "YouTubeProfileSpecific": {
        "properties": {
          "is_business_email_listed": {
            "description": "True when the channel lists a business email (shown to signed-in users only; the address is not returned); null otherwise, since YouTube shows nothing for a channel without one.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_official_artist_channel": {
            "description": "True for an Official Artist Channel (the note badge after its name), false for any other channel; null when the page shows no badge row (YouTube's built-in channels).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "is_subscriber_count_hidden": {
            "description": "True when the channel hides its subscriber count (metrics.follower_count is then null; neither its About panel nor its header shows one), false when YouTube shows it; null when that cannot be told (no About panel or header seen).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "keywords": {
            "description": "The channel's keywords as its owner wrote them, a quoted phrase as one keyword; [] when it has none (listed in unknown_fields when the source cannot see them).",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "keywords",
          "is_official_artist_channel",
          "is_subscriber_count_hidden",
          "is_business_email_listed"
        ],
        "type": "object"
      },
      "YoutubeCommentsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 20), newest first with sort=newest, YouTube's Top comments ranking with sort=popular.",
            "items": {
              "$ref": "#/components/schemas/Comment"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "YoutubePostResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Post"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "YoutubePostsResponse": {
        "properties": {
          "data": {
            "description": "Up to limit items (page size 48), newest first with sort=newest, oldest first with sort=oldest, YouTube's Popular order (most viewed first) with sort=popular.",
            "items": {
              "$ref": "#/components/schemas/Post"
            },
            "type": "array"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "page": {
            "$ref": "#/components/schemas/PageInfo"
          }
        },
        "required": [
          "data",
          "page",
          "meta"
        ],
        "type": "object"
      },
      "YoutubeProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Profile"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      },
      "YoutubeTranscriptResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Transcript"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKey": {
        "in": "header",
        "name": "x-api-key",
        "type": "apiKey"
      },
      "session": {
        "description": "The dashboard session (https://staging-fly.socialtap.dev/dashboard/), set by POST /v1/session after an emailed sign-in link. Browsers send it; API clients use the API key.",
        "in": "cookie",
        "name": "__Host-st_session",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "SocialTap returns public social media data from the major platforms, normalized into one JSON schema per resource. One API key, one credit balance, and you only pay for requests that succeed. Available now: ads on Facebook; comments on Rumble, TikTok and YouTube; posts on Facebook, Instagram, Rumble, TikTok and YouTube; profiles on Instagram, Rumble, Threads, TikTok and YouTube; transcripts on Facebook, Instagram, Rumble, TikTok and YouTube.\n\n**AI agents and coding assistants:** before writing integration code, read [llms.txt](https://staging-fly.socialtap.dev/llms.txt) (how to authenticate, pick an endpoint, paginate and handle errors, plus every endpoint), the [agent guide](https://staging-fly.socialtap.dev/docs/agents/) and the [API reference](https://staging-fly.socialtap.dev/docs/reference/). Every docs page is also Markdown: append `index.md` to its URL or send `Accept: text/markdown`.\n\nAuthenticate with the `x-api-key` header. Branch on `error.code`, never on `message`; retry only the codes an operation's `x-socialtap-retry` lists as retryable ([error codes](https://staging-fly.socialtap.dev/docs/errors/)). Plans do not limit request rate: a per-account runaway ceiling answers `rate_limited` with a `retry-after` header.\n\nEvery operation states its price in `x-socialtap-pricing` (credits per request, or per page for lists), list operations their cursor paging in `x-socialtap-pagination`.\n\nFailed requests and cache hits cost no credits.",
    "title": "SocialTap API",
    "version": "1"
  },
  "openapi": "3.1.0",
  "paths": {
    "/status.json": {
      "get": {
        "description": "Public, no API key. `status` is health from the scheduled canaries: an endpoint is degraded after repeated failed runs and healthy again after several passes; unknown until first checked, and again when the canary has not run recently. `success_rate` is the share of customer requests in the last `success_rate_window_minutes` that got an answer, measured where every request ends (failures on SocialTap's side, including capacity refusals, count against it; requests refused for credits or rate do not count), rounded down; null when there was too little traffic. Cached for 60 seconds.",
        "operationId": "status.get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "endpoints": {
                      "items": {
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "last_checked": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "since": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "Canary health; unknown until first checked, or when the canary has not run recently.",
                            "enum": [
                              "healthy",
                              "degraded",
                              "unknown"
                            ],
                            "type": "string"
                          },
                          "success_rate": {
                            "description": "Real-traffic success rate over the window (0..1, rounded down); null when there was too little traffic.",
                            "maximum": 1,
                            "minimum": 0,
                            "type": [
                              "number",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "status",
                          "since",
                          "last_checked",
                          "success_rate"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "generated_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "success_rate_window_minutes": {
                      "description": "Window of every endpoint's success_rate.",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "generated_at",
                    "environment",
                    "success_rate_window_minutes",
                    "endpoints"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Health document"
          }
        },
        "security": [],
        "summary": "Live health of every endpoint",
        "tags": [
          "Status"
        ],
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [],
          "retry_after_header": "retry-after",
          "retryable_codes": []
        }
      }
    },
    "/v1/account": {
      "get": {
        "description": "The account's balance and plan, the low-balance alert threshold, and the calling key: its mode, scopes, spend limit (with what it used this interval) and expiry. Free; never cached. A pending agent key may call it (and nothing else) to learn when its owner confirmed.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key sees the fixed test balance.",
        "operationId": "account.get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "api_key": {
                          "description": "The key that made this request; null for a dashboard session.",
                          "properties": {
                            "created_at": {
                              "description": "When the key was created, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "expires_at": {
                              "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "id": {
                              "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                              "type": "string"
                            },
                            "ip_allowlist": {
                              "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                              "items": {
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "last_used_at": {
                              "description": "About when the key was last used (updated at most hourly); null when never.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "mode": {
                              "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                              "enum": [
                                "live",
                                "test"
                              ],
                              "type": "string"
                            },
                            "name": {
                              "description": "Your label for the key.",
                              "type": "string"
                            },
                            "object": {
                              "description": "Always api_key.",
                              "enum": [
                                "api_key"
                              ],
                              "type": "string"
                            },
                            "prefix": {
                              "description": "The secret's first characters, to recognize it.",
                              "type": "string"
                            },
                            "revoked_at": {
                              "description": "When the key was revoked; null while it is not.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "scopes": {
                              "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                              "items": {
                                "enum": [
                                  "endpoints",
                                  "jobs",
                                  "account:read",
                                  "admin"
                                ],
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "spend_limit": {
                              "description": "The key's spend limit and what it used this interval; null when the key has none.",
                              "properties": {
                                "amount": {
                                  "description": "Most credits the key may spend per interval.",
                                  "type": "integer"
                                },
                                "interval": {
                                  "description": "Calendar day or month, UTC.",
                                  "enum": [
                                    "day",
                                    "month"
                                  ],
                                  "type": "string"
                                },
                                "resets_at": {
                                  "description": "Start of the next interval, RFC 3339 UTC.",
                                  "format": "date-time",
                                  "type": "string"
                                },
                                "used": {
                                  "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                  "type": "integer"
                                }
                              },
                              "required": [
                                "amount",
                                "interval",
                                "used",
                                "resets_at"
                              ],
                              "type": [
                                "object",
                                "null"
                              ]
                            },
                            "status": {
                              "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                              "enum": [
                                "active",
                                "pending",
                                "expired",
                                "revoked"
                              ],
                              "type": "string"
                            }
                          },
                          "required": [
                            "object",
                            "id",
                            "name",
                            "mode",
                            "status",
                            "prefix",
                            "scopes",
                            "spend_limit",
                            "expires_at",
                            "ip_allowlist",
                            "created_at",
                            "last_used_at",
                            "revoked_at"
                          ],
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "available": {
                          "description": "Credits new requests can set aside now: balance minus what requests in flight and unfinished jobs hold. For a busy account it may lag concurrent requests by about a second.",
                          "type": "integer"
                        },
                        "balance": {
                          "description": "Credits the account owns, including those held by requests in flight and unfinished jobs; for a test key, the fixed test balance.",
                          "type": "integer"
                        },
                        "created_at": {
                          "description": "When the account was created, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "email": {
                          "description": "The owner's email address: sign-in links, receipts and balance alerts go there.",
                          "type": "string"
                        },
                        "id": {
                          "description": "Account ID (acct_…).",
                          "type": "string"
                        },
                        "low_balance_threshold": {
                          "description": "credits.low fires (event and email) when a request takes the balance from above this to at or below it; null when off.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made this request. A test key sees the fixed test balance.",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": "string"
                        },
                        "object": {
                          "description": "Always account.",
                          "enum": [
                            "account"
                          ],
                          "type": "string"
                        },
                        "plan": {
                          "description": "Plan ID.",
                          "type": "string"
                        },
                        "status": {
                          "description": "unverified: created by an agent signup whose owner has not confirmed by email yet (no free credits, live keys pending).",
                          "enum": [
                            "active",
                            "unverified"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "email",
                        "status",
                        "plan",
                        "mode",
                        "balance",
                        "available",
                        "low_balance_threshold",
                        "api_key",
                        "created_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get the account, balance and calling key",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Get the account, balance and calling key",
        "tags": [
          "Account"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "patch": {
        "description": "Sets low_balance_threshold: credits.low (an event and an email to the owner) fires once each time a request takes the balance from above it to at or below it; credits.depleted fires when the balance reaches 0. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key's change is validated and answered but not stored: test mode never changes the live account.",
        "operationId": "account.update",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "low_balance_threshold": {
                    "description": "Credits; null turns credits.low off. Setting it never fires the event by itself: only a request that crosses it does.",
                    "maximum": 1000000000,
                    "minimum": 0,
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                },
                "required": [
                  "low_balance_threshold"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "api_key": {
                          "description": "The key that made this request; null for a dashboard session.",
                          "properties": {
                            "created_at": {
                              "description": "When the key was created, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "expires_at": {
                              "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "id": {
                              "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                              "type": "string"
                            },
                            "ip_allowlist": {
                              "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                              "items": {
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "last_used_at": {
                              "description": "About when the key was last used (updated at most hourly); null when never.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "mode": {
                              "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                              "enum": [
                                "live",
                                "test"
                              ],
                              "type": "string"
                            },
                            "name": {
                              "description": "Your label for the key.",
                              "type": "string"
                            },
                            "object": {
                              "description": "Always api_key.",
                              "enum": [
                                "api_key"
                              ],
                              "type": "string"
                            },
                            "prefix": {
                              "description": "The secret's first characters, to recognize it.",
                              "type": "string"
                            },
                            "revoked_at": {
                              "description": "When the key was revoked; null while it is not.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "scopes": {
                              "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                              "items": {
                                "enum": [
                                  "endpoints",
                                  "jobs",
                                  "account:read",
                                  "admin"
                                ],
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "spend_limit": {
                              "description": "The key's spend limit and what it used this interval; null when the key has none.",
                              "properties": {
                                "amount": {
                                  "description": "Most credits the key may spend per interval.",
                                  "type": "integer"
                                },
                                "interval": {
                                  "description": "Calendar day or month, UTC.",
                                  "enum": [
                                    "day",
                                    "month"
                                  ],
                                  "type": "string"
                                },
                                "resets_at": {
                                  "description": "Start of the next interval, RFC 3339 UTC.",
                                  "format": "date-time",
                                  "type": "string"
                                },
                                "used": {
                                  "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                  "type": "integer"
                                }
                              },
                              "required": [
                                "amount",
                                "interval",
                                "used",
                                "resets_at"
                              ],
                              "type": [
                                "object",
                                "null"
                              ]
                            },
                            "status": {
                              "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                              "enum": [
                                "active",
                                "pending",
                                "expired",
                                "revoked"
                              ],
                              "type": "string"
                            }
                          },
                          "required": [
                            "object",
                            "id",
                            "name",
                            "mode",
                            "status",
                            "prefix",
                            "scopes",
                            "spend_limit",
                            "expires_at",
                            "ip_allowlist",
                            "created_at",
                            "last_used_at",
                            "revoked_at"
                          ],
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "available": {
                          "description": "Credits new requests can set aside now: balance minus what requests in flight and unfinished jobs hold. For a busy account it may lag concurrent requests by about a second.",
                          "type": "integer"
                        },
                        "balance": {
                          "description": "Credits the account owns, including those held by requests in flight and unfinished jobs; for a test key, the fixed test balance.",
                          "type": "integer"
                        },
                        "created_at": {
                          "description": "When the account was created, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "email": {
                          "description": "The owner's email address: sign-in links, receipts and balance alerts go there.",
                          "type": "string"
                        },
                        "id": {
                          "description": "Account ID (acct_…).",
                          "type": "string"
                        },
                        "low_balance_threshold": {
                          "description": "credits.low fires (event and email) when a request takes the balance from above this to at or below it; null when off.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made this request. A test key sees the fixed test balance.",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": "string"
                        },
                        "object": {
                          "description": "Always account.",
                          "enum": [
                            "account"
                          ],
                          "type": "string"
                        },
                        "plan": {
                          "description": "Plan ID.",
                          "type": "string"
                        },
                        "status": {
                          "description": "unverified: created by an agent signup whose owner has not confirmed by email yet (no free credits, live keys pending).",
                          "enum": [
                            "active",
                            "unverified"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "email",
                        "status",
                        "plan",
                        "mode",
                        "balance",
                        "available",
                        "low_balance_threshold",
                        "api_key",
                        "created_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update account settings",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Update account settings",
        "tags": [
          "Account"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/agent_signup": {
      "post": {
        "description": "For AI agents: send your human's email address and get a test key that works at once (recorded responses, free) and a live key that stays pending until the human confirms by email, which grants the free credits. Agents never get spending power without a human. For an address that already has an account, no keys are made: the owner is emailed a sign-in link to create one in the dashboard, and the answer is 202 with the human signup's object (check your email).\n\n**Auth:** none.",
        "operationId": "agent_signup.create",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "email": {
                    "description": "Your human's email address: they confirm there before the live key works.",
                    "maxLength": 254,
                    "minLength": 3,
                    "type": "string"
                  },
                  "name": {
                    "description": "Your name as an agent, shown to the human and used as the keys' label: at most 40 ASCII letters, digits, spaces, hyphens, underscores or parentheses, starting with a letter or digit (anything else is invalid_input). Default: \"Agent\".",
                    "maxLength": 100,
                    "type": "string"
                  }
                },
                "required": [
                  "email"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "account_id": {
                          "description": "The new account (unverified until the human confirms).",
                          "type": "string"
                        },
                        "confirmation_expires_at": {
                          "description": "When the confirmation link stops working; then sign up again.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "email": {
                          "description": "Where the confirmation link was sent.",
                          "type": "string"
                        },
                        "free_credits": {
                          "description": "Credits the account gets when the human confirms.",
                          "type": "integer"
                        },
                        "live_key": {
                          "description": "Pending until the human confirms by email; until then it can only read GET /v1/account (poll api_key.status).",
                          "properties": {
                            "created_at": {
                              "description": "When the key was created, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "expires_at": {
                              "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "id": {
                              "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                              "type": "string"
                            },
                            "ip_allowlist": {
                              "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                              "items": {
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "last_used_at": {
                              "description": "About when the key was last used (updated at most hourly); null when never.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "mode": {
                              "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                              "enum": [
                                "live",
                                "test"
                              ],
                              "type": "string"
                            },
                            "name": {
                              "description": "Your label for the key.",
                              "type": "string"
                            },
                            "object": {
                              "description": "Always api_key.",
                              "enum": [
                                "api_key"
                              ],
                              "type": "string"
                            },
                            "prefix": {
                              "description": "The secret's first characters, to recognize it.",
                              "type": "string"
                            },
                            "revoked_at": {
                              "description": "When the key was revoked; null while it is not.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "scopes": {
                              "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                              "items": {
                                "enum": [
                                  "endpoints",
                                  "jobs",
                                  "account:read",
                                  "admin"
                                ],
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "secret": {
                              "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.",
                              "type": "string"
                            },
                            "spend_limit": {
                              "description": "The key's spend limit and what it used this interval; null when the key has none.",
                              "properties": {
                                "amount": {
                                  "description": "Most credits the key may spend per interval.",
                                  "type": "integer"
                                },
                                "interval": {
                                  "description": "Calendar day or month, UTC.",
                                  "enum": [
                                    "day",
                                    "month"
                                  ],
                                  "type": "string"
                                },
                                "resets_at": {
                                  "description": "Start of the next interval, RFC 3339 UTC.",
                                  "format": "date-time",
                                  "type": "string"
                                },
                                "used": {
                                  "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                  "type": "integer"
                                }
                              },
                              "required": [
                                "amount",
                                "interval",
                                "used",
                                "resets_at"
                              ],
                              "type": [
                                "object",
                                "null"
                              ]
                            },
                            "status": {
                              "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                              "enum": [
                                "active",
                                "pending",
                                "expired",
                                "revoked"
                              ],
                              "type": "string"
                            }
                          },
                          "required": [
                            "object",
                            "id",
                            "name",
                            "mode",
                            "status",
                            "prefix",
                            "scopes",
                            "spend_limit",
                            "expires_at",
                            "ip_allowlist",
                            "created_at",
                            "last_used_at",
                            "revoked_at",
                            "secret"
                          ],
                          "type": "object"
                        },
                        "object": {
                          "description": "Always agent_signup.",
                          "enum": [
                            "agent_signup"
                          ],
                          "type": "string"
                        },
                        "test_key": {
                          "description": "Works now: every endpoint answers from recorded responses, free. Build and test with it.",
                          "properties": {
                            "created_at": {
                              "description": "When the key was created, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "expires_at": {
                              "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "id": {
                              "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                              "type": "string"
                            },
                            "ip_allowlist": {
                              "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                              "items": {
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "last_used_at": {
                              "description": "About when the key was last used (updated at most hourly); null when never.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "mode": {
                              "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                              "enum": [
                                "live",
                                "test"
                              ],
                              "type": "string"
                            },
                            "name": {
                              "description": "Your label for the key.",
                              "type": "string"
                            },
                            "object": {
                              "description": "Always api_key.",
                              "enum": [
                                "api_key"
                              ],
                              "type": "string"
                            },
                            "prefix": {
                              "description": "The secret's first characters, to recognize it.",
                              "type": "string"
                            },
                            "revoked_at": {
                              "description": "When the key was revoked; null while it is not.",
                              "format": "date-time",
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "scopes": {
                              "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                              "items": {
                                "enum": [
                                  "endpoints",
                                  "jobs",
                                  "account:read",
                                  "admin"
                                ],
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "secret": {
                              "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.",
                              "type": "string"
                            },
                            "spend_limit": {
                              "description": "The key's spend limit and what it used this interval; null when the key has none.",
                              "properties": {
                                "amount": {
                                  "description": "Most credits the key may spend per interval.",
                                  "type": "integer"
                                },
                                "interval": {
                                  "description": "Calendar day or month, UTC.",
                                  "enum": [
                                    "day",
                                    "month"
                                  ],
                                  "type": "string"
                                },
                                "resets_at": {
                                  "description": "Start of the next interval, RFC 3339 UTC.",
                                  "format": "date-time",
                                  "type": "string"
                                },
                                "used": {
                                  "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                  "type": "integer"
                                }
                              },
                              "required": [
                                "amount",
                                "interval",
                                "used",
                                "resets_at"
                              ],
                              "type": [
                                "object",
                                "null"
                              ]
                            },
                            "status": {
                              "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                              "enum": [
                                "active",
                                "pending",
                                "expired",
                                "revoked"
                              ],
                              "type": "string"
                            }
                          },
                          "required": [
                            "object",
                            "id",
                            "name",
                            "mode",
                            "status",
                            "prefix",
                            "scopes",
                            "spend_limit",
                            "expires_at",
                            "ip_allowlist",
                            "created_at",
                            "last_used_at",
                            "revoked_at",
                            "secret"
                          ],
                          "type": "object"
                        }
                      },
                      "required": [
                        "object",
                        "account_id",
                        "email",
                        "free_credits",
                        "confirmation_expires_at",
                        "test_key",
                        "live_key"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Sign up as an agent: a test key now, live on confirm",
            "headers": {
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "email": {
                          "description": "Where the link was sent.",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the link stops working, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always signup.",
                          "enum": [
                            "signup"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "email",
                        "expires_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The address already has an account: no keys were made; its owner was emailed a sign-in link to create a key for you in the dashboard. Ask them to check their email.",
            "headers": {
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [],
        "summary": "Sign up as an agent: a test key now, live on confirm",
        "tags": [
          "Signup"
        ],
        "x-socialtap-auth": {
          "auth": "none",
          "scope": ""
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/api_keys": {
      "get": {
        "description": "The account's keys, newest first, revoked ones included; never their secrets. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key sees and manages test keys only.",
        "operationId": "api_keys.list",
        "parameters": [
          {
            "description": "Only keys of this mode. A test key always sees test keys only.",
            "in": "query",
            "name": "mode",
            "schema": {
              "enum": [
                "live",
                "test"
              ],
              "type": "string"
            }
          },
          {
            "description": "Keys per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "created_at": {
                            "description": "When the key was created, RFC 3339 UTC.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "expires_at": {
                            "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "id": {
                            "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                            "type": "string"
                          },
                          "ip_allowlist": {
                            "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "last_used_at": {
                            "description": "About when the key was last used (updated at most hourly); null when never.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "mode": {
                            "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                            "enum": [
                              "live",
                              "test"
                            ],
                            "type": "string"
                          },
                          "name": {
                            "description": "Your label for the key.",
                            "type": "string"
                          },
                          "object": {
                            "description": "Always api_key.",
                            "enum": [
                              "api_key"
                            ],
                            "type": "string"
                          },
                          "prefix": {
                            "description": "The secret's first characters, to recognize it.",
                            "type": "string"
                          },
                          "revoked_at": {
                            "description": "When the key was revoked; null while it is not.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "scopes": {
                            "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                            "items": {
                              "enum": [
                                "endpoints",
                                "jobs",
                                "account:read",
                                "admin"
                              ],
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "spend_limit": {
                            "description": "The key's spend limit and what it used this interval; null when the key has none.",
                            "properties": {
                              "amount": {
                                "description": "Most credits the key may spend per interval.",
                                "type": "integer"
                              },
                              "interval": {
                                "description": "Calendar day or month, UTC.",
                                "enum": [
                                  "day",
                                  "month"
                                ],
                                "type": "string"
                              },
                              "resets_at": {
                                "description": "Start of the next interval, RFC 3339 UTC.",
                                "format": "date-time",
                                "type": "string"
                              },
                              "used": {
                                "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                "type": "integer"
                              }
                            },
                            "required": [
                              "amount",
                              "interval",
                              "used",
                              "resets_at"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                            "enum": [
                              "active",
                              "pending",
                              "expired",
                              "revoked"
                            ],
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "name",
                          "mode",
                          "status",
                          "prefix",
                          "scopes",
                          "spend_limit",
                          "expires_at",
                          "ip_allowlist",
                          "created_at",
                          "last_used_at",
                          "revoked_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List API keys",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List API keys",
        "tags": [
          "API keys"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "post": {
        "description": "Creates a key with the given scopes, spend limit, expiry and IP allowlist. The secret is in this answer only: store it now. A key never gets a scope its creator lacks. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key sees and manages test keys only.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "api_keys.create",
        "parameters": [
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "expires_at": {
                    "description": "RFC 3339, in the future. Default: never; made with an API key, that key's expiry (never later).",
                    "format": "date-time",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "ip_allowlist": {
                    "description": "IP addresses or CIDR ranges (203.0.113.0/24, 2001:db8::/32). Default: [] (any); made with an API key, that key's allowlist (every entry within it).",
                    "items": {
                      "maxLength": 64,
                      "type": "string"
                    },
                    "maxItems": 50,
                    "type": "array"
                  },
                  "mode": {
                    "description": "Default: the mode of the credential creating it. A test key can only create test keys.",
                    "enum": [
                      "live",
                      "test"
                    ],
                    "type": "string"
                  },
                  "name": {
                    "description": "Your label for the key. Default: \"API key\".",
                    "maxLength": 100,
                    "type": "string"
                  },
                  "scopes": {
                    "description": "Default: endpoints, jobs and account:read. Only an admin credential creates keys, and a key never gets a scope its creator lacks.",
                    "items": {
                      "enum": [
                        "endpoints",
                        "jobs",
                        "account:read",
                        "admin"
                      ],
                      "type": "string"
                    },
                    "maxItems": 4,
                    "minItems": 1,
                    "type": "array"
                  },
                  "spend_limit": {
                    "description": "Default: none; made with an API key, that key's own (never looser: ADR 0011 §9 key restrictions).",
                    "properties": {
                      "amount": {
                        "description": "Most credits the key may spend per interval; above it, requests fail with spend_limit_reached.",
                        "maximum": 1000000000,
                        "minimum": 1,
                        "type": "integer"
                      },
                      "interval": {
                        "description": "Calendar day or month, UTC.",
                        "enum": [
                          "day",
                          "month"
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "amount",
                      "interval"
                    ],
                    "type": [
                      "object",
                      "null"
                    ]
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "description": "When the key was created, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                          "type": "string"
                        },
                        "ip_allowlist": {
                          "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "last_used_at": {
                          "description": "About when the key was last used (updated at most hourly); null when never.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": "string"
                        },
                        "name": {
                          "description": "Your label for the key.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always api_key.",
                          "enum": [
                            "api_key"
                          ],
                          "type": "string"
                        },
                        "prefix": {
                          "description": "The secret's first characters, to recognize it.",
                          "type": "string"
                        },
                        "revoked_at": {
                          "description": "When the key was revoked; null while it is not.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scopes": {
                          "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                          "items": {
                            "enum": [
                              "endpoints",
                              "jobs",
                              "account:read",
                              "admin"
                            ],
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "secret": {
                          "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.",
                          "type": "string"
                        },
                        "spend_limit": {
                          "description": "The key's spend limit and what it used this interval; null when the key has none.",
                          "properties": {
                            "amount": {
                              "description": "Most credits the key may spend per interval.",
                              "type": "integer"
                            },
                            "interval": {
                              "description": "Calendar day or month, UTC.",
                              "enum": [
                                "day",
                                "month"
                              ],
                              "type": "string"
                            },
                            "resets_at": {
                              "description": "Start of the next interval, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "used": {
                              "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "amount",
                            "interval",
                            "used",
                            "resets_at"
                          ],
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                          "enum": [
                            "active",
                            "pending",
                            "expired",
                            "revoked"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "name",
                        "mode",
                        "status",
                        "prefix",
                        "scopes",
                        "spend_limit",
                        "expires_at",
                        "ip_allowlist",
                        "created_at",
                        "last_used_at",
                        "revoked_at",
                        "secret"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Create an API key",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Create an API key",
        "tags": [
          "API keys"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/api_keys/{id}": {
      "delete": {
        "description": "Revokes a key for good (a key may revoke itself). It stops working within a minute everywhere; revoking it again changes nothing. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key sees and manages test keys only.",
        "operationId": "api_keys.revoke",
        "parameters": [
          {
            "description": "Key ID (key_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "description": "When the key was created, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                          "type": "string"
                        },
                        "ip_allowlist": {
                          "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "last_used_at": {
                          "description": "About when the key was last used (updated at most hourly); null when never.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": "string"
                        },
                        "name": {
                          "description": "Your label for the key.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always api_key.",
                          "enum": [
                            "api_key"
                          ],
                          "type": "string"
                        },
                        "prefix": {
                          "description": "The secret's first characters, to recognize it.",
                          "type": "string"
                        },
                        "revoked_at": {
                          "description": "When the key was revoked; null while it is not.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scopes": {
                          "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                          "items": {
                            "enum": [
                              "endpoints",
                              "jobs",
                              "account:read",
                              "admin"
                            ],
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "spend_limit": {
                          "description": "The key's spend limit and what it used this interval; null when the key has none.",
                          "properties": {
                            "amount": {
                              "description": "Most credits the key may spend per interval.",
                              "type": "integer"
                            },
                            "interval": {
                              "description": "Calendar day or month, UTC.",
                              "enum": [
                                "day",
                                "month"
                              ],
                              "type": "string"
                            },
                            "resets_at": {
                              "description": "Start of the next interval, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "used": {
                              "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "amount",
                            "interval",
                            "used",
                            "resets_at"
                          ],
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                          "enum": [
                            "active",
                            "pending",
                            "expired",
                            "revoked"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "name",
                        "mode",
                        "status",
                        "prefix",
                        "scopes",
                        "spend_limit",
                        "expires_at",
                        "ip_allowlist",
                        "created_at",
                        "last_used_at",
                        "revoked_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Revoke an API key",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Revoke an API key",
        "tags": [
          "API keys"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "get": {
        "description": "One key and its spend this interval; never its secret. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key sees and manages test keys only.",
        "operationId": "api_keys.get",
        "parameters": [
          {
            "description": "Key ID (key_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "description": "When the key was created, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                          "type": "string"
                        },
                        "ip_allowlist": {
                          "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "last_used_at": {
                          "description": "About when the key was last used (updated at most hourly); null when never.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": "string"
                        },
                        "name": {
                          "description": "Your label for the key.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always api_key.",
                          "enum": [
                            "api_key"
                          ],
                          "type": "string"
                        },
                        "prefix": {
                          "description": "The secret's first characters, to recognize it.",
                          "type": "string"
                        },
                        "revoked_at": {
                          "description": "When the key was revoked; null while it is not.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scopes": {
                          "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                          "items": {
                            "enum": [
                              "endpoints",
                              "jobs",
                              "account:read",
                              "admin"
                            ],
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "spend_limit": {
                          "description": "The key's spend limit and what it used this interval; null when the key has none.",
                          "properties": {
                            "amount": {
                              "description": "Most credits the key may spend per interval.",
                              "type": "integer"
                            },
                            "interval": {
                              "description": "Calendar day or month, UTC.",
                              "enum": [
                                "day",
                                "month"
                              ],
                              "type": "string"
                            },
                            "resets_at": {
                              "description": "Start of the next interval, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "used": {
                              "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "amount",
                            "interval",
                            "used",
                            "resets_at"
                          ],
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                          "enum": [
                            "active",
                            "pending",
                            "expired",
                            "revoked"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "name",
                        "mode",
                        "status",
                        "prefix",
                        "scopes",
                        "spend_limit",
                        "expires_at",
                        "ip_allowlist",
                        "created_at",
                        "last_used_at",
                        "revoked_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get an API key",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Get an API key",
        "tags": [
          "API keys"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "patch": {
        "description": "Changes a key's name, scopes, spend limit, expiry or IP allowlist; absent fields keep their value. Takes effect within a minute everywhere. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key sees and manages test keys only.",
        "operationId": "api_keys.update",
        "parameters": [
          {
            "description": "Key ID (key_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "expires_at": {
                    "description": "New expiry (RFC 3339, in the future); null: never expires.",
                    "format": "date-time",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "ip_allowlist": {
                    "description": "New allowlist; [] or null: any IP.",
                    "items": {
                      "maxLength": 64,
                      "type": "string"
                    },
                    "maxItems": 50,
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "name": {
                    "description": "New label.",
                    "maxLength": 100,
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "scopes": {
                    "description": "New scopes (never more than the caller's own).",
                    "items": {
                      "enum": [
                        "endpoints",
                        "jobs",
                        "account:read",
                        "admin"
                      ],
                      "type": "string"
                    },
                    "maxItems": 4,
                    "minItems": 1,
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "spend_limit": {
                    "description": "New spend limit; null removes it.",
                    "properties": {
                      "amount": {
                        "description": "Most credits the key may spend per interval; above it, requests fail with spend_limit_reached.",
                        "maximum": 1000000000,
                        "minimum": 1,
                        "type": "integer"
                      },
                      "interval": {
                        "description": "Calendar day or month, UTC.",
                        "enum": [
                          "day",
                          "month"
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "amount",
                      "interval"
                    ],
                    "type": [
                      "object",
                      "null"
                    ]
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "description": "When the key was created, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                          "type": "string"
                        },
                        "ip_allowlist": {
                          "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "last_used_at": {
                          "description": "About when the key was last used (updated at most hourly); null when never.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": "string"
                        },
                        "name": {
                          "description": "Your label for the key.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always api_key.",
                          "enum": [
                            "api_key"
                          ],
                          "type": "string"
                        },
                        "prefix": {
                          "description": "The secret's first characters, to recognize it.",
                          "type": "string"
                        },
                        "revoked_at": {
                          "description": "When the key was revoked; null while it is not.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scopes": {
                          "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                          "items": {
                            "enum": [
                              "endpoints",
                              "jobs",
                              "account:read",
                              "admin"
                            ],
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "spend_limit": {
                          "description": "The key's spend limit and what it used this interval; null when the key has none.",
                          "properties": {
                            "amount": {
                              "description": "Most credits the key may spend per interval.",
                              "type": "integer"
                            },
                            "interval": {
                              "description": "Calendar day or month, UTC.",
                              "enum": [
                                "day",
                                "month"
                              ],
                              "type": "string"
                            },
                            "resets_at": {
                              "description": "Start of the next interval, RFC 3339 UTC.",
                              "format": "date-time",
                              "type": "string"
                            },
                            "used": {
                              "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "amount",
                            "interval",
                            "used",
                            "resets_at"
                          ],
                          "type": [
                            "object",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                          "enum": [
                            "active",
                            "pending",
                            "expired",
                            "revoked"
                          ],
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "name",
                        "mode",
                        "status",
                        "prefix",
                        "scopes",
                        "spend_limit",
                        "expires_at",
                        "ip_allowlist",
                        "created_at",
                        "last_used_at",
                        "revoked_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update an API key",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Update an API key",
        "tags": [
          "API keys"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/billing/checkout": {
      "post": {
        "description": "Creates a Stripe Checkout session for a credit pack; open the returned url to pay. Credits are added when payment completes.",
        "operationId": "billing.checkout.create",
        "parameters": [
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "pack": {
                    "description": "Pack ID.",
                    "enum": [
                      "20k",
                      "80k",
                      "400k",
                      "2m"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "pack"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Checkout session"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Buy a credit pack (Stripe Checkout)",
        "tags": [
          "Billing"
        ],
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/credit_transactions": {
      "get": {
        "description": "Every change to the balance, newest first, cursor-paged: grants (free credits), purchases, hourly usage roll-ups and adjustments. Per-request detail is in GET /v1/usage. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key gets an empty report: test requests are not metered.",
        "operationId": "credit_transactions.list",
        "parameters": [
          {
            "description": "Only this kind.",
            "in": "query",
            "name": "type",
            "schema": {
              "enum": [
                "grant",
                "purchase",
                "usage",
                "adjustment"
              ],
              "type": "string"
            }
          },
          {
            "description": "Created at or after: RFC 3339 or a date (UTC).",
            "in": "query",
            "name": "since",
            "schema": {
              "maxLength": 40,
              "type": "string"
            }
          },
          {
            "description": "Created before: RFC 3339 or a date (UTC).",
            "in": "query",
            "name": "until",
            "schema": {
              "maxLength": 40,
              "type": "string"
            }
          },
          {
            "description": "Transactions per page (default 25, at most 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "balance_after": {
                            "description": "The ledger's balance after this transaction. Usage is recorded hourly, so the live balance (GET /v1/account) may be lower.",
                            "type": "integer"
                          },
                          "created_at": {
                            "description": "When it was recorded, RFC 3339 UTC.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "credits": {
                            "description": "Credits added (positive) or spent (negative).",
                            "type": "integer"
                          },
                          "description": {
                            "description": "What it was, for humans.",
                            "type": "string"
                          },
                          "id": {
                            "description": "Transaction ID (ctx_…).",
                            "type": "string"
                          },
                          "object": {
                            "description": "Always credit_transaction.",
                            "enum": [
                              "credit_transaction"
                            ],
                            "type": "string"
                          },
                          "type": {
                            "description": "grant: free credits (signup) or a goodwill grant; purchase: a credit pack; usage: credits spent, rolled up per hour; adjustment: a correction by support, unspent credits of a refunded or disputed purchase taken back, or given back when a dispute is won. New values may be added.",
                            "enum": [
                              "grant",
                              "purchase",
                              "usage",
                              "adjustment"
                            ],
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "type",
                          "credits",
                          "balance_after",
                          "description",
                          "created_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List credit transactions (the ledger)",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List credit transactions (the ledger)",
        "tags": [
          "Account"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/docs_feedback": {
      "post": {
        "description": "Records whether a docs page helped, with an optional comment: what every docs page's \"Was this page helpful?\" sends. Agents are welcome to report a page that was wrong, unclear or missing something (set `agent`). Free; limited per IP address.\n\n**Auth:** none.",
        "operationId": "docs_feedback.create",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "agent": {
                    "description": "True when an AI agent sends it (an agent's view of the docs is as useful as a human's).",
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "comment": {
                    "description": "What was missing or wrong, in the reader's words. Never include API keys or personal data.",
                    "maxLength": 2000,
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "helpful": {
                    "description": "Whether the page answered the reader's question.",
                    "type": "boolean"
                  },
                  "path": {
                    "description": "The docs page the feedback is about: its path on the site (/docs/pagination/), optionally with a #section.",
                    "maxLength": 512,
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "path",
                  "helpful"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "object": {
                          "description": "Always docs_feedback.",
                          "enum": [
                            "docs_feedback"
                          ],
                          "type": "string"
                        },
                        "path": {
                          "description": "The page the feedback was recorded for.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "path"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Send feedback on a docs page",
            "headers": {
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [],
        "summary": "Send feedback on a docs page",
        "tags": [
          "Docs"
        ],
        "x-socialtap-auth": {
          "auth": "none",
          "scope": ""
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/events": {
      "get": {
        "description": "Every event of the account, newest first, whether or not a webhook endpoint received it: what webhooks would have delivered. Kept `events_retention_s` (30 days). Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key sees test events only (a test job's job.* events and webhook.test); credits.* and api_key.* events are live only.",
        "operationId": "events.list",
        "parameters": [
          {
            "description": "Only events of this type (an event type, or a prefix wildcard such as job.*).",
            "in": "query",
            "name": "type",
            "schema": {
              "maxLength": 64,
              "type": "string"
            }
          },
          {
            "description": "Events per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page; omit to start from the newest.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "data": {
                            "description": "The type's data object (small: a summary plus links)."
                          },
                          "id": {
                            "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                            "type": "string"
                          },
                          "object": {
                            "description": "Always event.",
                            "enum": [
                              "event"
                            ],
                            "type": "string"
                          },
                          "timestamp": {
                            "description": "When it happened.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "type": {
                            "description": "The event type (event types table); new types may be added.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "type",
                          "timestamp",
                          "data"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List events, newest first",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List events, newest first",
        "tags": [
          "Events"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "description": "One event, as webhooks deliver it. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key sees test events only (a test job's job.* events and webhook.test); credits.* and api_key.* events are live only.",
        "operationId": "events.get",
        "parameters": [
          {
            "description": "Event ID (evt_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "data": {
                          "description": "The type's data object (small: a summary plus links)."
                        },
                        "id": {
                          "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always event.",
                          "enum": [
                            "event"
                          ],
                          "type": "string"
                        },
                        "timestamp": {
                          "description": "When it happened.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "type": {
                          "description": "The event type (event types table); new types may be added.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "type",
                        "timestamp",
                        "data"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get an event",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Get an event",
        "tags": [
          "Events"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/events/{id}/redeliver": {
      "post": {
        "description": "Queues a new delivery of the event (same `webhook-id`, so receivers deduplicate it) to one endpoint, or to every enabled endpoint subscribed to its type. The answer lists the deliveries queued (one page). Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key sees test events only (a test job's job.* events and webhook.test); credits.* and api_key.* events are live only.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "events.redeliver",
        "parameters": [
          {
            "description": "Event ID (evt_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "webhook_endpoint_id": {
                    "description": "Deliver to this endpoint only; default: every enabled endpoint subscribed to the event's type.",
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "attempts": {
                            "description": "Attempts made so far.",
                            "type": "integer"
                          },
                          "created_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "delivered_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "duration_ms": {
                            "description": "The last attempt's duration.",
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "error": {
                            "description": "Why the last attempt failed when there was no response.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "event_type": {
                            "type": "string"
                          },
                          "id": {
                            "description": "whd_…",
                            "type": "string"
                          },
                          "next_attempt_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "object": {
                            "description": "Always webhook_delivery.",
                            "enum": [
                              "webhook_delivery"
                            ],
                            "type": "string"
                          },
                          "response_excerpt": {
                            "description": "The start of the last response body.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "pending: an attempt is due (next_attempt_at). failed: every attempt failed, or the endpoint was disabled or deleted.",
                            "enum": [
                              "pending",
                              "succeeded",
                              "failed"
                            ],
                            "type": "string"
                          },
                          "status_code": {
                            "description": "The last attempt's HTTP status; null when it got none (timeout, refused, blocked URL).",
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "webhook_endpoint_id": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "event_id",
                          "event_type",
                          "webhook_endpoint_id",
                          "status",
                          "attempts",
                          "status_code",
                          "duration_ms",
                          "response_excerpt",
                          "error",
                          "created_at",
                          "delivered_at",
                          "next_attempt_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Deliver an event again",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Deliver an event again",
        "tags": [
          "Events"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/facebook/post": {
      "get": {
        "description": "Returns a public Facebook post, photo, video or reel: its text with hashtags and mentions, the author with their verification badge, the publish time, every photo of an album and the video's file, thumbnail, size and duration, the shared link card or reshared post, and the exact reaction, comment, share and view counts with the reactions by type. Accepts post, permalink, photo, reel, watch, video, fb.watch and share links or a numeric ID.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/facebook/post/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/facebook/post/"
        },
        "operationId": "facebook.post.get",
        "parameters": [
          {
            "description": "Facebook post, photo, video or reel URL: /<page>/posts/<id>, permalink.php and story.php links, /photo/?fbid= and /<page>/photos/… links, reel, watch, video.php and /<page>/videos/… links, fb.watch and /share/p|v|r/ share links (m., mbasic. and web. hosts too), or a numeric post, photo or video ID.",
            "example": "https://www.facebook.com/reel/4075684206061398/",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Facebook post, photo, video or reel URL: /<page>/posts/<id>, permalink.php and story.php links, /photo/?fbid= and /<page>/photos/… links, reel, watch, video.php and /<page>/videos/… links, fb.watch and /share/p|v|r/ share links (m., mbasic. and web. hosts too), or a numeric post, photo or video ID.",
              "examples": [
                "https://www.facebook.com/reel/4075684206061398/"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [],
                        "author": {
                          "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/243095782_416661036495945_3843362260429099279_n.png?stp=cp0_dst-png&cstp=mx800x800&ctp=s80x80&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b…",
                          "display_name": "NASA - National Aeronautics and Space Administration",
                          "id": "100044561550831",
                          "is_verified": true,
                          "url": "https://www.facebook.com/NASA",
                          "username": "NASA"
                        },
                        "coauthors": [],
                        "duration_ms": 39381,
                        "hashtags": [],
                        "id": "1670768087751894",
                        "is_nsfw": null,
                        "is_pinned": null,
                        "is_sponsored": null,
                        "language": null,
                        "media": [
                          {
                            "alt_text": null,
                            "duration_ms": 39381,
                            "expires_at": "2026-10-25T18:00:00Z",
                            "height": 2160,
                            "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t15.5256-10/877658791_1832631854542515_4430770165954872904_n.jpg?stp=dst-jpg_tt6&cstp=mx1920x1080&ctp=s960x960&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…",
                            "type": "video",
                            "url": "https://video-atl3-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQMS1Kmor5hpvEHAtxe3lVPcxOt4prhHPFgKMLcPxvBSvELFTPbkpMPfDvKx8gg5c4VOCCZrgCV0tzqv9ahLzz1s3O0N2Cdf2DaUFGeUSO0WTA.mp4?_nc_cat=106&_nc_sid=SCRUBBED&_nc_ht=video-atl3-1.xx.fbcdn.net&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=SCRUBBE…",
                            "width": 3840
                          }
                        ],
                        "mentions": [
                          "CanadianSpaceAgency",
                          "ISS"
                        ],
                        "metrics": {
                          "comment_count": 55,
                          "like_count": 574,
                          "quote_count": null,
                          "repost_count": null,
                          "save_count": null,
                          "share_count": null,
                          "view_count": 52713
                        },
                        "platform": "facebook",
                        "platform_specific": {
                          "facebook": {
                            "feedback_id": "ZmVlZGJhY2s6MTY3MDc2ODA4Nzc1MTg5NA==",
                            "link": null,
                            "reactions": [
                              {
                                "count": 476,
                                "type": "like"
                              },
                              {
                                "count": 70,
                                "type": "love"
                              },
                              {
                                "count": 13,
                                "type": "care"
                              }
                            ],
                            "shared_post": null,
                            "video_id": "4075684206061398"
                          }
                        },
                        "platform_type": "reel",
                        "published_at": "2026-10-29T11:48:37Z",
                        "text": "NASA astronaut Anil Menon and Canadian Space Agency astronaut Joshua Kutryk are getting ready to head out of the International Space Station!\n \nAt this point, they have donned spacesuits called Extravehicular Mobility Units (EMUs), which contain all the protections and life suppo…",
                        "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t15.5256-10/877658791_1832631854542515_4430770165954872904_n.jpg?stp=dst-jpg_tt6&cstp=mx1920x1080&ctp=s960x960&_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_n…",
                        "title": null,
                        "type": "video",
                        "unknown_fields": [],
                        "url": "https://www.facebook.com/reel/4075684206061398/"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "facebook",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "1670768087751894",
                          "url": "https://www.facebook.com/reel/4075684206061398/"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/FacebookPostResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Facebook post, photo, video or reel with exact counts",
        "tags": [
          "Facebook"
        ],
        "x-socialtap-endpoint": "facebook.post",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/facebook/search_ads": {
      "get": {
        "description": "Searches Meta's public Ad Library by keyword and returns the matching ads that ran on Facebook, Instagram, Messenger, Threads and the Audience Network: the advertiser's page, the days the ad first and last ran, whether it is still active, where it ran, and each creative's headline, text, link, call to action, images and videos. Political and social-issue ads also carry the disclosed payer and Meta's impressions, reach and spend ranges. Filter by country, language, active status and the day an ad first ran; results come in the Ad Library's own order, most impressions first.\n\nReturns `{data, page, meta}`: `data` holds up to 10 `Ad` items (the shared schema, the same on every platform), most impressions first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit (api) per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/"
        },
        "operationId": "facebook.search_ads.list",
        "parameters": [
          {
            "description": "Keywords matched against the ad's text, in any order. Wrap the query in double quotes (\"cold brew\") to match an exact phrase.",
            "example": "coffee",
            "in": "query",
            "name": "query",
            "required": true,
            "schema": {
              "description": "Keywords matched against the ad's text, in any order. Wrap the query in double quotes (\"cold brew\") to match an exact phrase.",
              "examples": [
                "coffee"
              ],
              "maxLength": 200,
              "type": "string"
            }
          },
          {
            "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads delivered in this country. All countries when omitted.",
            "example": "US",
            "in": "query",
            "name": "country",
            "schema": {
              "description": "Region: an ISO 3166-1 alpha-2 country code such as US or BR (case-insensitive). Only ads delivered in this country. All countries when omitted.",
              "examples": [
                "US"
              ],
              "type": "string"
            }
          },
          {
            "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only ads whose text Meta detects as this language (the primary subtag counts: pt-BR searches pt). All languages when omitted.",
            "example": "en",
            "in": "query",
            "name": "lang",
            "schema": {
              "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Only ads whose text Meta detects as this language (the primary subtag counts: pt-BR searches pt). All languages when omitted.",
              "examples": [
                "en"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items that are still running (active), only items that stopped (inactive), or both (all). Default: all.",
            "example": "all",
            "in": "query",
            "name": "status",
            "schema": {
              "default": "all",
              "description": "Only items that are still running (active), only items that stopped (inactive), or both (all). Default: all.",
              "enum": [
                "active",
                "inactive",
                "all"
              ],
              "examples": [
                "active"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they ran during the window: an ad that last ran (last_shown_at) before since is left out; active ads ran until today.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Ads count when they ran during the window: an ad that last ran (last_shown_at) before since is left out; active ads ran until today.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they ran during the window: an ad that first ran (first_shown_at) at or after until is left out.",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Ads count when they ran during the window: an ad that first ran (first_shown_at) at or after until is left out.",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 10,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 10,
              "maximum": 10,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "advertiser": {
                            "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/739782028_1533198008291919_1079542453788497101_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…",
                            "display_name": "American Health Support Community",
                            "id": "966175593248497",
                            "is_verified": null,
                            "url": "https://www.facebook.com/61588018263996",
                            "username": null
                          },
                          "approximate_fields": [
                            "first_shown_at"
                          ],
                          "audience_size": null,
                          "country_codes": [],
                          "creatives": [
                            {
                              "body": "My aunt called me a creep for putting a camera in Nana’s living room.\n\nNana called me practical.\n\nThen the camera caught something worse than a fall.\n\nI need to be clear about one thing before anyone decides what kind of grandson I am.\n\nNana asked for the camera.\n\nNot me.\n\nNot my…",
                              "cta_text": "Learn more",
                              "link_description": null,
                              "link_url": "https://shop.pipitea.com/hbt/kd/sp-nm",
                              "media": [
                                {
                                  "alt_text": null,
                                  "duration_ms": null,
                                  "expires_at": "2026-10-25T18:00:00Z",
                                  "height": null,
                                  "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/742001725_2100792434176297_9060645049521596104_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…",
                                  "type": "image",
                                  "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/742501415_1706621370582971_4085631001896338504_n.jpg?_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380",
                                  "width": null
                                }
                              ],
                              "title": "Natural Relief in Weeks"
                            }
                          ],
                          "first_shown_at": "2026-07-18T07:00:00Z",
                          "id": "2619351891814847",
                          "impressions": null,
                          "is_active": true,
                          "is_political": false,
                          "languages": [],
                          "last_shown_at": null,
                          "paid_by": null,
                          "platform": "facebook",
                          "platform_specific": {},
                          "publisher_platforms": [
                            "facebook",
                            "instagram",
                            "audience_network"
                          ],
                          "reach": null,
                          "spend": null,
                          "type": "image",
                          "unknown_fields": [],
                          "url": "https://www.facebook.com/ads/library/?id=2619351891814847"
                        },
                        {
                          "advertiser": {
                            "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/712623693_1599994994434095_1320701223312676781_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…",
                            "display_name": "American Health Support Community",
                            "id": "966175593248497",
                            "is_verified": null,
                            "url": "https://www.facebook.com/61588018263996",
                            "username": null
                          },
                          "approximate_fields": [
                            "first_shown_at"
                          ],
                          "audience_size": null,
                          "country_codes": [],
                          "creatives": [
                            {
                              "body": "I almost looked past the woman who saved my husband's life. She was seventy-nine, sitting alone at the booth next to ours at the Cracker Barrel off Highway 31. A glass of milk in front of her. She kept stirring it. She wasn't eating.\n\nIf I'd known, the night I leaned over and ask…",
                              "cta_text": "Learn more",
                              "link_description": "\"I've tried everything to support my kidney function naturally. Fish oil, CoQ10, cutting protein, stressing about every meal. Nothing moved the needle enough to satisfy my doctor. Hibiscus tea is the first thing that actually showed up in my numbers. It's been 3 months and my eGF…",
                              "link_url": "https://shop.pipitea.com/hbt/kd/sp",
                              "media": [
                                {
                                  "alt_text": null,
                                  "duration_ms": null,
                                  "expires_at": "2026-10-25T18:00:00Z",
                                  "height": null,
                                  "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/711729685_1717035472767079_186136568392095276_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED…",
                                  "type": "image",
                                  "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/713729791_868879862958547_7409366389733397444_n.jpg?_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380",
                                  "width": null
                                }
                              ],
                              "title": "Natural Relief in Weeks"
                            }
                          ],
                          "first_shown_at": "2026-06-01T07:00:00Z",
                          "id": "1923645134954720",
                          "impressions": null,
                          "is_active": true,
                          "is_political": false,
                          "languages": [],
                          "last_shown_at": null,
                          "paid_by": null,
                          "platform": "facebook",
                          "platform_specific": {},
                          "publisher_platforms": [
                            "facebook",
                            "instagram",
                            "audience_network"
                          ],
                          "reach": null,
                          "spend": null,
                          "type": "image",
                          "unknown_fields": [],
                          "url": "https://www.facebook.com/ads/library/?id=1923645134954720"
                        },
                        {
                          "advertiser": {
                            "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/712025330_1303417705276292_736671271727941526_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&o…",
                            "display_name": "American Health Support Community",
                            "id": "966175593248497",
                            "is_verified": null,
                            "url": "https://www.facebook.com/61588018263996",
                            "username": null
                          },
                          "approximate_fields": [
                            "first_shown_at"
                          ],
                          "audience_size": null,
                          "country_codes": [],
                          "creatives": [
                            {
                              "body": "I almost looked past the woman who saved my husband's life. She was seventy-nine, sitting alone at the booth next to ours at the Cracker Barrel off Highway 31. A glass of milk in front of her. She kept stirring it. She wasn't eating.\n\nIf I'd known, the night I leaned over and ask…",
                              "cta_text": "Learn more",
                              "link_description": "\"I've tried everything to support my kidney function naturally. Fish oil, CoQ10, cutting protein, stressing about every meal. Nothing moved the needle enough to satisfy my doctor. Hibiscus tea is the first thing that actually showed up in my numbers. It's been 3 months and my eGF…",
                              "link_url": "https://shop.pipitea.com/hbt/kd/sp",
                              "media": [
                                {
                                  "alt_text": null,
                                  "duration_ms": null,
                                  "expires_at": "2026-10-25T18:00:00Z",
                                  "height": null,
                                  "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/711737708_4485707625086258_2353150069319301753_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…",
                                  "type": "image",
                                  "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/710755472_911440771966686_1736050619245168045_n.jpg?_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380",
                                  "width": null
                                }
                              ],
                              "title": "Natural Relief in Weeks"
                            }
                          ],
                          "first_shown_at": "2026-06-01T07:00:00Z",
                          "id": "2140497416496021",
                          "impressions": null,
                          "is_active": true,
                          "is_political": false,
                          "languages": [],
                          "last_shown_at": null,
                          "paid_by": null,
                          "platform": "facebook",
                          "platform_specific": {},
                          "publisher_platforms": [
                            "facebook",
                            "instagram",
                            "audience_network"
                          ],
                          "reach": null,
                          "spend": null,
                          "type": "image",
                          "unknown_fields": [],
                          "url": "https://www.facebook.com/ads/library/?id=2140497416496021"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "facebook",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": null,
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/FacebookSearch_adsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Search Meta's Ad Library by keyword",
        "tags": [
          "Facebook"
        ],
        "x-socialtap-endpoint": "facebook.search_ads",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 3600,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "most impressions first",
          "page_max": 10,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "api"
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "ad",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/facebook/transcript": {
      "get": {
        "description": "Returns the timed transcript of a public Facebook video or reel: the uploaded or auto-generated caption track when Facebook has one, otherwise speech-to-text on the video's audio. Accepts reel, watch, page video, video.php, fb.watch and share links, or a numeric video ID.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/"
        },
        "operationId": "facebook.transcript.get",
        "parameters": [
          {
            "description": "Facebook video URL (reel, watch, page video, video.php, m./mbasic./web. hosts, fb.watch and share/v|r links) or a numeric video ID.",
            "example": "https://www.facebook.com/reel/1803909017420449/",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Facebook video URL (reel, watch, page video, video.php, m./mbasic./web. hosts, fb.watch and share/v|r links) or a numeric video ID.",
              "examples": [
                "https://www.facebook.com/reel/1803909017420449"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "available_languages": [
                          "en-US"
                        ],
                        "duration_ms": 59861,
                        "id": "1803909017420449",
                        "is_auto_generated": false,
                        "language": "en-US",
                        "platform": "facebook",
                        "platform_specific": {},
                        "segments": [
                          {
                            "end_ms": 4000,
                            "start_ms": 33,
                            "text": "But the standard that we should continuously aspire to exceed,"
                          },
                          {
                            "end_ms": 7166,
                            "start_ms": 4000,
                            "text": "which is why we are bringing that intensity, that discipline, that"
                          },
                          {
                            "end_ms": 11400,
                            "start_ms": 7166,
                            "text": "engineering ownership back to NASA, because great nations do not remain great"
                          }
                        ],
                        "source": "captions",
                        "text": "But the standard that we should continuously aspire to exceed, which is why we are bringing that intensity, that discipline, that engineering ownership back to NASA, because great nations do not remain great by being caretakers of history, but by continuously making history. We h…",
                        "url": "https://www.facebook.com/reel/1803909017420449/"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "facebook",
                        "source": "captions",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 1517,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "1803909017420449",
                          "url": "https://www.facebook.com/reel/1803909017420449/"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/FacebookTranscriptResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "no_transcript": {
                    "$ref": "#/components/examples/no_transcript"
                  },
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.\n\n`no_transcript`: The media exists but has no transcript: no caption track and no speech to transcribe. Do not retry; try another language with lang if the platform offers one.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Facebook video transcript",
        "tags": [
          "Facebook"
        ],
        "x-socialtap-endpoint": "facebook.transcript",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 122,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "captions"
            },
            {
              "credits": 2,
              "label": "2 credits + 2 per started minute of media",
              "max": 122,
              "per": 2,
              "source": "asr",
              "unit": "media_minute",
              "unit_max": 60
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "transcript",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/instagram/post": {
      "get": {
        "description": "Returns a public Instagram post, reel or carousel: the caption with its hashtags and mentions, the author and any collaborators, the publish time, every carousel item's image or video URL with its size, duration and alt text, and the like, comment and (for single videos) view counts. Accepts post, reel, tv, instagr.am and share links or a raw shortcode.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/instagram/post/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/instagram/post/"
        },
        "operationId": "instagram.post.get",
        "parameters": [
          {
            "description": "Instagram post, reel or carousel URL (instagram.com/p/…, /reel/…, /reels/…, /tv/…, /<username>/p/…, m.instagram.com, instagr.am, instagram.com/share/… links) or a raw shortcode. Tracking params and img_index are ignored: the whole post is returned.",
            "example": "https://www.instagram.com/reel/De1S3KpCXf0/",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Instagram post, reel or carousel URL (instagram.com/p/…, /reel/…, /reels/…, /tv/…, /<username>/p/…, m.instagram.com, instagr.am, instagram.com/share/… links) or a raw shortcode. Tracking params and img_index are ignored: the whole post is returned.",
              "examples": [
                "https://www.instagram.com/reel/De1S3KpCXf0/"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [],
                        "author": {
                          "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_gid=S…",
                          "display_name": "National Geographic",
                          "id": "787132",
                          "is_verified": true,
                          "url": "https://www.instagram.com/natgeo/",
                          "username": "natgeo"
                        },
                        "coauthors": [
                          {
                            "avatar_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.2885-19/293493364_162817252949028_8275460966213229030_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=108&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.cdninstagram.com&_nc_ss=7b6…",
                            "display_name": "National Geographic Society",
                            "id": "4757225830",
                            "is_verified": true,
                            "url": "https://www.instagram.com/natgeosociety/",
                            "username": "natgeosociety"
                          },
                          {
                            "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/11419091_505296402966021_797003013_a.jpg?_nc_cat=101&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b689&oh=SCRUBBED&oe=F2A52380",
                            "display_name": "Joel Sartore- Photo Ark",
                            "id": "225429667",
                            "is_verified": true,
                            "url": "https://www.instagram.com/joelsartore/",
                            "username": "joelsartore"
                          },
                          {
                            "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-19/681945023_18592998970017301_7811445524976503069_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_gid=S…",
                            "display_name": "National Geographic Animals",
                            "id": "1029649300",
                            "is_verified": true,
                            "url": "https://www.instagram.com/natgeoanimals/",
                            "username": "natgeoanimals"
                          }
                        ],
                        "duration_ms": 23744,
                        "hashtags": [
                          "PhotoArk"
                        ],
                        "id": "De1S3KpCXf0",
                        "is_nsfw": null,
                        "is_pinned": null,
                        "is_sponsored": null,
                        "language": null,
                        "media": [
                          {
                            "alt_text": "Video by National Geographic on October 23, 2026. May be an image of snail and text.",
                            "duration_ms": 23744,
                            "expires_at": "2026-10-25T18:00:00Z",
                            "height": 1920,
                            "thumbnail_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-15/862543567_18711062458019133_8845814561108513720_n.jpg?stp=dst-jpg_e15_tt6&_nc_cat=105&ig_cache_key=NDAxNDE5NzU5ODcwNDk5MDE5NjE4NzExMDYyNDUyMDE5MTMz.3-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=…",
                            "type": "video",
                            "url": "https://scontent-atl3-1.cdninstagram.com/o1/v/t2/f2/m86/AQO0Zc3E_eoYHXxPOVvPDNzjiHnCGoREl8vxeookIy4831a0VLAN6T9CITX0dyH2cQS6Dy0fs5SGxYC42fWpG2JeAvlnP9yrsgmHUk8.mp4?_nc_cat=106&_nc_sid=SCRUBBED&_nc_ht=scontent-atl3-1.cdninstagram.com&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=S…",
                            "width": 1080
                          }
                        ],
                        "mentions": [
                          "joelsartore",
                          "natgeoanimals",
                          "natgeosociety"
                        ],
                        "metrics": {
                          "comment_count": 238,
                          "like_count": 68253,
                          "quote_count": null,
                          "repost_count": null,
                          "save_count": null,
                          "share_count": null,
                          "view_count": 759188
                        },
                        "platform": "instagram",
                        "platform_specific": {
                          "instagram": {
                            "is_ai_generated": null
                          }
                        },
                        "platform_type": "reel",
                        "published_at": "2026-10-23T10:01:35Z",
                        "text": "Warning—looking at nudibranchs may cause excessive awe. @joelsartore loves these little creatures, and so do we. 💛🧡🩷\n\nWe’re celebrating 20 years of the National Geographic #PhotoArk, an audacious project documenting the world's incredible biodiversity and highlighting the importa…",
                        "thumbnail_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-15/862543567_18711062458019133_8845814561108513720_n.jpg?stp=dst-jpg_e35_s640x640_tt6&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc…",
                        "title": null,
                        "type": "video",
                        "unknown_fields": [],
                        "url": "https://www.instagram.com/reel/De1S3KpCXf0/"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "instagram",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "post",
                          "id": "De1S3KpCXf0",
                          "url": "https://www.instagram.com/reel/De1S3KpCXf0/"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/InstagramPostResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Instagram post, reel or carousel with media and metrics",
        "tags": [
          "Instagram"
        ],
        "x-socialtap-endpoint": "instagram.post",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/instagram/posts": {
      "get": {
        "description": "Returns a public Instagram account's posts, reels and carousels as they appear on its profile grid, newest first, page by page: caption with hashtags and mentions, publish time, author and collaborators, every carousel item's image or video with its size and duration, tagged accounts, pinned posts, and like, comment and (for videos) view counts. Accepts a username or any profile link.\n\nReturns `{data, page, meta}`: `data` holds up to 12 `Post` items (the shared schema, the same on every platform), newest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/instagram/posts/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/instagram/posts/"
        },
        "operationId": "instagram.posts.list",
        "parameters": [
          {
            "description": "Instagram username with or without the @, or a profile URL (instagram.com/nasa, m.instagram.com, instagr.am, a /reels/ or /tagged/ tab, an instagram.com/_u/ app link). Numeric user IDs are not accepted: Instagram does not resolve them logged out.",
            "example": "nasa",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "Instagram username with or without the @, or a profile URL (instagram.com/nasa, m.instagram.com, instagr.am, a /reels/ or /tagged/ tab, an instagram.com/_u/ app link). Numeric user IDs are not accepted: Instagram does not resolve them logged out.",
              "examples": [
                "nasa"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 12,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 12,
              "maximum": 12,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b689&…",
                            "display_name": "NASA",
                            "id": "528817151",
                            "is_verified": true,
                            "url": "https://www.instagram.com/nasa/",
                            "username": "nasa"
                          },
                          "coauthors": [
                            {
                              "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/93880139_247576663101568_4560165171292536832_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b689&…",
                              "display_name": "NASA Solar System Exploration",
                              "id": "1611722079",
                              "is_verified": true,
                              "url": "https://www.instagram.com/nasasolarsystem/",
                              "username": "nasasolarsystem"
                            },
                            {
                              "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-19/670016304_18577283653042671_4689932669633757619_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_gid=S…",
                              "display_name": "NASA Artemis",
                              "id": "1104426670",
                              "is_verified": true,
                              "url": "https://www.instagram.com/nasaartemis/",
                              "username": "nasaartemis"
                            }
                          ],
                          "duration_ms": 43767,
                          "hashtags": [
                            "NASA",
                            "ArtemisII",
                            "Artemis"
                          ],
                          "id": "DeTUk4sDSp-",
                          "is_nsfw": null,
                          "is_pinned": true,
                          "is_sponsored": false,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 43767,
                              "expires_at": "2026-10-25T18:00:00Z",
                              "height": 1908,
                              "thumbnail_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-15/842191580_18656578867049152_4200499629839780998_n.jpg?stp=dst-jpg_e15_tt6&_nc_cat=111&ig_cache_key=NDAwNDYzNDk4OTM2MjQ4OTk4MjE4NjU2NTc4ODYxMDQ5MTUy.3-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=…",
                              "type": "video",
                              "url": "https://scontent-atl3-2.cdninstagram.com/o1/v/t2/f2/m86/AQNUvreb47JFAC3mKM7kF_weYHzhiVF-MfERm99CfyBTok0ezeRdbVW8cH5NXn4mxO8gVi6j1GQ2RU9i4ByvKCLVPHdDruUpsCKYDQI.mp4?_nc_cat=105&_nc_sid=SCRUBBED&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ohc=SCRUBBED&efg=SCRUBBED&ccb=SCRUBBED&vs=S…",
                              "width": 1074
                            }
                          ],
                          "mentions": [
                            "nasaartemis",
                            "nasasolarsystem"
                          ],
                          "metrics": {
                            "comment_count": 7628,
                            "like_count": 755597,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 11075076
                          },
                          "platform": "instagram",
                          "platform_specific": {
                            "instagram": {
                              "is_ai_generated": false
                            }
                          },
                          "platform_type": "reel",
                          "published_at": "2026-10-10T15:15:02Z",
                          "text": "POV: you're watching the Earth set\n\nWe just released hundreds of new images and hours of new audio from our Artemis II mission around the Moon this spring. Check out our link in bio for the Artemis II Preliminary Lunar Science Report.\n\n#NASA #ArtemisII #Artemis",
                          "thumbnail_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-15/842191580_18656578867049152_4200499629839780998_n.jpg?stp=c0.417.1074.1074a_dst-jpg_e15_tt6&_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.cdninstagra…",
                          "title": null,
                          "type": "video",
                          "unknown_fields": [],
                          "url": "https://www.instagram.com/reel/DeTUk4sDSp-/"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/432029380_939863124412845_4074172309041694202_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b689…",
                            "display_name": "NASA Webb Telescope",
                            "id": "549313808",
                            "is_verified": true,
                            "url": "https://www.instagram.com/nasawebb/",
                            "username": "nasawebb"
                          },
                          "coauthors": [
                            {
                              "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/437785305_1498177207718392_5285428334541669140_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b…",
                              "display_name": "NASA Universe",
                              "id": "65495240044",
                              "is_verified": true,
                              "url": "https://www.instagram.com/nasauniverse/",
                              "username": "nasauniverse"
                            },
                            {
                              "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b689&…",
                              "display_name": "NASA",
                              "id": "528817151",
                              "is_verified": true,
                              "url": "https://www.instagram.com/nasa/",
                              "username": "nasa"
                            }
                          ],
                          "duration_ms": null,
                          "hashtags": [],
                          "id": "DeJ28eTxo4s",
                          "is_nsfw": null,
                          "is_pinned": true,
                          "is_sponsored": false,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": null,
                              "expires_at": "2026-10-25T18:00:00Z",
                              "height": 1872,
                              "thumbnail_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/838879752_18633093571001809_7013098794556155636_n.jpg?stp=c64.0.1872.1872a_dst-jpg_e35_s1080x1080_sh2.08_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-a…",
                              "type": "image",
                              "url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/838879752_18633093571001809_7013098794556155636_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=109&ig_cache_key=NDAwMTk3MTM5NDExOTYzNDQ3Ng%3D%3D.3-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=…",
                              "width": 2000
                            }
                          ],
                          "mentions": [
                            "NASAWebb",
                            "nasa",
                            "nasauniverse"
                          ],
                          "metrics": {
                            "comment_count": 1027,
                            "like_count": 290040,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": null
                          },
                          "platform": "instagram",
                          "platform_specific": {
                            "instagram": {
                              "is_ai_generated": false
                            }
                          },
                          "platform_type": "post",
                          "published_at": "2026-10-06T13:10:11Z",
                          "text": "Brewing up new stars 🪄\n \n@NASAWebb’s unique view of the stellar nursery known as NGC 7129 reveals numerous stars formerly hidden in this cosmic cauldron. \n \nStars begin their life in cold, dense regions of dust and gas, hiding from view of most telescopes. Webb’s high degree of i…",
                          "thumbnail_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/838879752_18633093571001809_7013098794556155636_n.jpg?stp=c64.0.1872.1872a_dst-jpg_e35_s1080x1080_sh2.08_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-a…",
                          "title": null,
                          "type": "image",
                          "unknown_fields": [],
                          "url": "https://www.instagram.com/p/DeJ28eTxo4s/"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_ss=7b689&…",
                            "display_name": "NASA",
                            "id": "528817151",
                            "is_verified": true,
                            "url": "https://www.instagram.com/nasa/",
                            "username": "nasa"
                          },
                          "coauthors": [],
                          "duration_ms": null,
                          "hashtags": [
                            "NASA",
                            "Space",
                            "Stars"
                          ],
                          "id": "DeAYvsnn4la",
                          "is_nsfw": null,
                          "is_pinned": true,
                          "is_sponsored": false,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": null,
                              "expires_at": "2026-10-25T18:00:00Z",
                              "height": 1350,
                              "thumbnail_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/831222439_18653890615049152_5346150317938845760_n.jpg?stp=c0.135.1080.1080a_dst-jpg_e15_s1080x1080_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.…",
                              "type": "image",
                              "url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/831222439_18653890615049152_5346150317938845760_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=110&ig_cache_key=Mzk5OTMwNDc1ODAwMTk1MzE5OA%3D%3D.3-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=…",
                              "width": 1080
                            },
                            {
                              "alt_text": null,
                              "duration_ms": null,
                              "expires_at": "2026-10-25T18:00:00Z",
                              "height": 1350,
                              "thumbnail_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/830418338_18653890612049152_312587861543217627_n.jpg?stp=c0.135.1080.1080a_dst-jpg_e15_s1080x1080_tt6&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.c…",
                              "type": "image",
                              "url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/830418338_18653890612049152_312587861543217627_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=100&ig_cache_key=Mzk5OTMwNDc1ODM0NjExNzEyOA%3D%3D.3-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=2…",
                              "width": 1080
                            },
                            {
                              "alt_text": null,
                              "duration_ms": null,
                              "expires_at": "2026-10-25T18:00:00Z",
                              "height": 1350,
                              "thumbnail_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-15/831354642_18653890627049152_4381034991606753149_n.jpg?stp=c0.135.1080.1080a_dst-jpg_e15_s1080x1080_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.…",
                              "type": "image",
                              "url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-15/831354642_18653890627049152_4381034991606753149_n.jpg?stp=dst-jpg_e35_tt6&_nc_cat=104&ig_cache_key=Mzk5OTMwNDc2MDcwMzExNzQxOA%3D%3D.3-ccb7-5&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=…",
                              "width": 1080
                            }
                          ],
                          "mentions": [
                            "NASAWebb"
                          ],
                          "metrics": {
                            "comment_count": 5550,
                            "like_count": 1353320,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": null
                          },
                          "platform": "instagram",
                          "platform_specific": {
                            "instagram": {
                              "is_ai_generated": false
                            }
                          },
                          "platform_type": "post",
                          "published_at": "2026-10-02T20:52:45Z",
                          "text": "Swipe for countless stars\n\nSagittarius B2 is the most massive and most active star-forming region in the Milky Way. It produces half of the stars in our home galaxy’s core.\n\nThis image of Sagittarius B2 was taken by our @NASAWebb telescope.\n\n#NASA #Space #Stars",
                          "thumbnail_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-15/831222439_18653890615049152_5346150317938845760_n.jpg?stp=c0.135.1080.1080a_dst-jpg_e15_s1080x1080_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-1.…",
                          "title": null,
                          "type": "carousel",
                          "unknown_fields": [],
                          "url": "https://www.instagram.com/p/DeAYvsnn4la/"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "instagram",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "528817151",
                          "url": "https://www.instagram.com/nasa/"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/InstagramPostsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "A public Instagram account's posts, reels and carousels",
        "tags": [
          "Instagram"
        ],
        "x-socialtap-endpoint": "instagram.posts",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 86400,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "newest first",
          "page_max": 12,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": ""
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/instagram/profile": {
      "get": {
        "description": "Returns a public Instagram account: user ID, username, display name, bio, the links in its bio with their titles, profile picture, verification badge, whether the account is private, and exact follower, following and post counts, plus Instagram's own fields (Meta-wide ID, memorialized, live story, highlights, pronouns). Accepts a username with or without the @ or any instagram.com profile link.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/instagram/profile/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/profile/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/profile/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/instagram/profile/"
        },
        "operationId": "instagram.profile.get",
        "parameters": [
          {
            "description": "Instagram username with or without the @ (natgeo, @natgeo), or a profile link (instagram.com/natgeo, with or without a tab such as /reels/ or /tagged/, m.instagram.com, instagr.am, instagram.com/_u/natgeo, instagram.com/stories/natgeo/, with any query such as ?igsh=…). Usernames are case-insensitive. A bare number is a username: numeric user IDs are not accepted.",
            "example": "https://www.instagram.com/natgeo/",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "Instagram username with or without the @ (natgeo, @natgeo), or a profile link (instagram.com/natgeo, with or without a tab such as /reels/ or /tagged/, m.instagram.com, instagr.am, instagram.com/_u/natgeo, instagram.com/stories/natgeo/, with any query such as ?igsh=…). Usernames are case-insensitive. A bare number is a username: numeric user IDs are not accepted.",
              "examples": [
                "natgeo"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [],
                        "avatar_url": "https://scontent-atl3-2.cdninstagram.com/v/t51.82787-19/683576066_18653628823019133_9051036240972105113_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=1&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.cdninstagram.com&_nc_gid=S…",
                        "banner_url": null,
                        "bio": "Step into wonder and find your inner explorer with National Geographic 🌎",
                        "category": null,
                        "country_code": null,
                        "created_at": null,
                        "display_name": "National Geographic",
                        "external_links": [
                          {
                            "title": null,
                            "url": "http://visitstore.bio/natgeo"
                          },
                          {
                            "title": "Subscribe Here!",
                            "url": "https://ngmdomsubs.nationalgeographic.com/servlet/OrdersGateway?cds_mag_code=NGM&cds_page_id=283562&cds_response_key=I5FX10002"
                          }
                        ],
                        "id": "787132",
                        "is_private": false,
                        "is_verified": true,
                        "location": null,
                        "metrics": {
                          "follower_count": 268266804,
                          "following_count": 195,
                          "post_count": 32123,
                          "total_like_count": null,
                          "total_view_count": null
                        },
                        "platform": "instagram",
                        "platform_specific": {
                          "instagram": {
                            "fbid": "17841400573960012",
                            "is_highlights_shown": true,
                            "is_memorialized": false,
                            "is_story_live": true,
                            "pronouns": []
                          }
                        },
                        "type": "unknown",
                        "unknown_fields": [],
                        "url": "https://www.instagram.com/natgeo/",
                        "username": "natgeo"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "instagram",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "787132",
                          "url": "https://www.instagram.com/natgeo/"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/InstagramProfileResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Public Instagram profile with exact follower counts",
        "tags": [
          "Instagram"
        ],
        "x-socialtap-endpoint": "instagram.profile",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "profile",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/instagram/transcript": {
      "get": {
        "description": "Returns the timed transcript of a public Instagram reel or video post. Instagram rarely exposes caption tracks to logged-out clients, so most transcripts are speech-to-text on the post's audio. Accepts reel, post, tv, instagr.am and share links or a raw shortcode; for carousels, img_index selects the item.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/"
        },
        "operationId": "instagram.transcript.get",
        "parameters": [
          {
            "description": "Instagram reel/post URL (instagram.com/reel/…, /reels/…, /p/…, /tv/…, instagr.am, instagram.com/share/… links) or a raw shortcode. For carousel posts, ?img_index=N selects the item; default is the first video.",
            "example": "https://www.instagram.com/p/De1S3KpCXf0/",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Instagram reel/post URL (instagram.com/reel/…, /reels/…, /p/…, /tv/…, instagr.am, instagram.com/share/… links) or a raw shortcode. For carousel posts, ?img_index=N selects the item; default is the first video.",
              "examples": [
                "https://www.instagram.com/reel/De1S3KpCXf0/"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "available_languages": [],
                        "duration_ms": 23745,
                        "id": "De1S3KpCXf0",
                        "is_auto_generated": true,
                        "language": "en",
                        "platform": "instagram",
                        "platform_specific": {},
                        "segments": [
                          {
                            "end_ms": 3580,
                            "start_ms": 0,
                            "text": "You are looking at nudibranchs. You ever seen anything that crazy looking?"
                          },
                          {
                            "end_ms": 9220,
                            "start_ms": 3800,
                            "text": "Every color in the rainbow. These are marine snails basically that have lost their shells"
                          },
                          {
                            "end_ms": 13480,
                            "start_ms": 9220,
                            "text": "over time and developed these elaborate colors. Usually brightly colored animals are toxic."
                          }
                        ],
                        "source": "asr",
                        "text": "You are looking at nudibranchs. You ever seen anything that crazy looking? Every color in the rainbow. These are marine snails basically that have lost their shells over time and developed these elaborate colors. Usually brightly colored animals are toxic. Some of these are, some…",
                        "url": "https://www.instagram.com/reel/De1S3KpCXf0/"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "instagram",
                        "source": "asr",
                        "is_cached": false,
                        "credits_charged": 4,
                        "latency_ms": 4125,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "De1S3KpCXf0",
                          "url": "https://www.instagram.com/reel/De1S3KpCXf0/"
                        },
                        "credits_remaining": 9996,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/InstagramTranscriptResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "no_transcript": {
                    "$ref": "#/components/examples/no_transcript"
                  },
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.\n\n`no_transcript`: The media exists but has no transcript: no caption track and no speech to transcribe. Do not retry; try another language with lang if the platform offers one.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Instagram reel / video transcript",
        "tags": [
          "Instagram"
        ],
        "x-socialtap-endpoint": "instagram.transcript",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 122,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "captions"
            },
            {
              "credits": 2,
              "label": "2 credits + 2 per started minute of media",
              "max": 122,
              "per": 2,
              "source": "asr",
              "unit": "media_minute",
              "unit_max": 60
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "transcript",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/jobs": {
      "get": {
        "description": "The account's jobs, newest first, cursor-paged. Records are kept `records_retention_s` (30 days) after a job ends. Free.\n\n**Auth:** an API key with the `jobs` scope, or the dashboard session.\n\n**Test mode:** A test key's job runs every item in test mode: each gets its endpoint's test-mode answer (recorded responses, magic inputs), free; nothing is held or charged. A test key sees test jobs only.",
        "operationId": "jobs.list",
        "parameters": [
          {
            "description": "Only jobs in this status.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "queued",
                "running",
                "canceling",
                "completed",
                "canceled",
                "expired"
              ],
              "type": "string"
            }
          },
          {
            "description": "Jobs per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page; omit to start from the newest.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "cancel_requested_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "created_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "credits": {
                            "properties": {
                              "charged": {
                                "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                                "type": "integer"
                              },
                              "max": {
                                "description": "max_credits: the most the job may spend.",
                                "type": "integer"
                              },
                              "reserved": {
                                "description": "Credits its running pages may still use (0 once the job ends).",
                                "type": "integer"
                              }
                            },
                            "required": [
                              "max",
                              "reserved",
                              "charged"
                            ],
                            "type": "object"
                          },
                          "expires_at": {
                            "description": "The deadline: items not ended by then expire.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "finished_at": {
                            "description": "When the job ended; null while it runs.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "id": {
                            "description": "The job ID (job_…).",
                            "type": "string"
                          },
                          "max_age": {
                            "description": "The job's max_age; null when it accepts no cached results.",
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "metadata": {
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "Your metadata; {} when none.",
                            "type": "object"
                          },
                          "object": {
                            "description": "Always job.",
                            "enum": [
                              "job"
                            ],
                            "type": "string"
                          },
                          "request_counts": {
                            "properties": {
                              "canceled": {
                                "type": "integer"
                              },
                              "expired": {
                                "type": "integer"
                              },
                              "failed": {
                                "type": "integer"
                              },
                              "queued": {
                                "description": "Not started.",
                                "type": "integer"
                              },
                              "running": {
                                "description": "Started (fetching, waiting for a retry or walking pages).",
                                "type": "integer"
                              },
                              "succeeded": {
                                "type": "integer"
                              },
                              "total": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "total",
                              "queued",
                              "running",
                              "succeeded",
                              "failed",
                              "canceled",
                              "expired"
                            ],
                            "type": "object"
                          },
                          "results_expire_at": {
                            "description": "When results are deleted; null while the job runs.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "results_url": {
                            "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "results_url_expires_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "started_at": {
                            "description": "When the first item started; null before.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.",
                            "enum": [
                              "queued",
                              "running",
                              "canceling",
                              "completed",
                              "canceled",
                              "expired"
                            ],
                            "type": "string"
                          },
                          "webhook_url": {
                            "description": "The job's own webhook URL; null when none.",
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "status",
                          "request_counts",
                          "credits",
                          "max_age",
                          "metadata",
                          "webhook_url",
                          "created_at",
                          "started_at",
                          "finished_at",
                          "cancel_requested_at",
                          "expires_at",
                          "results_url",
                          "results_url_expires_at",
                          "results_expire_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List jobs, newest first",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List jobs, newest first",
        "tags": [
          "Jobs"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "jobs"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "post": {
        "description": "Runs up to `max_requests` (1000) endpoint requests in the background: each item is exactly the request its endpoint answers synchronously, at the same price (failed items are free), with the same caches. `max_pages` walks a list endpoint server-side with its cursor. Credits work as for synchronous requests: each page reserves its endpoint's minimum when it runs (against the balance and the calling key's spend limit) and is topped up to its price, so a job starts whenever its first page could run; `max_credits` (default: the sum of every item's maximum price) caps what the job may spend. With `wait`, the answer is 200 with the first page of results when the job ends in time (a synchronous batch), else 202 with the job; poll `GET /v1/jobs/{id}` (free) or subscribe to `job.completed`.\n\n**Auth:** an API key with the `jobs` scope, or the dashboard session.\n\n**Test mode:** A test key's job runs every item in test mode: each gets its endpoint's test-mode answer (recorded responses, magic inputs), free; nothing is held or charged. A test key sees test jobs only.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "jobs.create",
        "parameters": [
          {
            "description": "Seconds to wait for the job to end before answering. If it ends in time the answer is 200 with the first page of results (a synchronous batch); otherwise 202 with the job as it is.",
            "in": "query",
            "name": "wait",
            "schema": {
              "maximum": 60,
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "max_age": {
                    "description": "Accept cached results up to this many seconds old for every item (free cache hits), like the endpoints' max_age.",
                    "minimum": 0,
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "max_credits": {
                    "description": "Most the job may spend: a cap, never held up front (each page reserves as a synchronous request does). Default: the sum of every item's maximum price (times its max_pages). Items that would go over it are canceled.",
                    "minimum": 1,
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "metadata": {
                    "additionalProperties": {
                      "maxLength": 500,
                      "type": "string"
                    },
                    "description": "Up to 16 string pairs of your own, returned with the job and in its events.",
                    "type": "object"
                  },
                  "requests": {
                    "description": "The requests to run, 1 to 1000; custom_id must be unique within the job.",
                    "items": {
                      "properties": {
                        "custom_id": {
                          "description": "Your ID for the item (letters, digits, _ and -), echoed on its results.",
                          "maxLength": 64,
                          "minLength": 1,
                          "type": "string"
                        },
                        "endpoint": {
                          "description": "The endpoint ID: Endpoint ID on its reference page, x-socialtap-endpoint in OpenAPI (youtube.transcript; not its operationId or path).",
                          "enum": [
                            "facebook.post",
                            "facebook.search_ads",
                            "facebook.transcript",
                            "instagram.post",
                            "instagram.posts",
                            "instagram.profile",
                            "instagram.transcript",
                            "rumble.comments",
                            "rumble.post",
                            "rumble.posts",
                            "rumble.profile",
                            "rumble.search_posts",
                            "rumble.transcript",
                            "threads.profile",
                            "tiktok.comments",
                            "tiktok.post",
                            "tiktok.posts",
                            "tiktok.profile",
                            "tiktok.transcript",
                            "youtube.comments",
                            "youtube.post",
                            "youtube.posts",
                            "youtube.profile",
                            "youtube.transcript"
                          ],
                          "type": "string"
                        },
                        "max_pages": {
                          "description": "List endpoints only: walk up to this many pages with the cursor (default 1). Each page is a result and costs a page's price.",
                          "maximum": 1000,
                          "minimum": 1,
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "params": {
                          "additionalProperties": {},
                          "description": "The endpoint's query params, as you would send them to it (strings, numbers or booleans).",
                          "type": "object"
                        }
                      },
                      "required": [
                        "custom_id",
                        "endpoint",
                        "params"
                      ],
                      "type": "object"
                    },
                    "maxItems": 1000,
                    "minItems": 1,
                    "type": "array"
                  },
                  "webhook_url": {
                    "description": "Also deliver this job's job.* events to this URL: the URL of one of the account's webhook endpoints (its secret signs them).",
                    "maxLength": 2048,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "requests"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "cancel_requested_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "credits": {
                          "properties": {
                            "charged": {
                              "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                              "type": "integer"
                            },
                            "max": {
                              "description": "max_credits: the most the job may spend.",
                              "type": "integer"
                            },
                            "reserved": {
                              "description": "Credits its running pages may still use (0 once the job ends).",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "max",
                            "reserved",
                            "charged"
                          ],
                          "type": "object"
                        },
                        "expires_at": {
                          "description": "The deadline: items not ended by then expire.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "finished_at": {
                          "description": "When the job ended; null while it runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "The job ID (job_…).",
                          "type": "string"
                        },
                        "max_age": {
                          "description": "The job's max_age; null when it accepts no cached results.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "metadata": {
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Your metadata; {} when none.",
                          "type": "object"
                        },
                        "object": {
                          "description": "Always job.",
                          "enum": [
                            "job"
                          ],
                          "type": "string"
                        },
                        "request_counts": {
                          "properties": {
                            "canceled": {
                              "type": "integer"
                            },
                            "expired": {
                              "type": "integer"
                            },
                            "failed": {
                              "type": "integer"
                            },
                            "queued": {
                              "description": "Not started.",
                              "type": "integer"
                            },
                            "running": {
                              "description": "Started (fetching, waiting for a retry or walking pages).",
                              "type": "integer"
                            },
                            "succeeded": {
                              "type": "integer"
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "total",
                            "queued",
                            "running",
                            "succeeded",
                            "failed",
                            "canceled",
                            "expired"
                          ],
                          "type": "object"
                        },
                        "results_expire_at": {
                          "description": "When results are deleted; null while the job runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url": {
                          "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url_expires_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "started_at": {
                          "description": "When the first item started; null before.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.",
                          "enum": [
                            "queued",
                            "running",
                            "canceling",
                            "completed",
                            "canceled",
                            "expired"
                          ],
                          "type": "string"
                        },
                        "webhook_url": {
                          "description": "The job's own webhook URL; null when none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "status",
                        "request_counts",
                        "credits",
                        "max_age",
                        "metadata",
                        "webhook_url",
                        "created_at",
                        "started_at",
                        "finished_at",
                        "cancel_requested_at",
                        "expires_at",
                        "results_url",
                        "results_url_expires_at",
                        "results_expire_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "results": {
                      "description": "Only on 200 from create with wait: the first page of results.",
                      "items": {
                        "properties": {
                          "completed_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "custom_id": {
                            "type": "string"
                          },
                          "endpoint": {
                            "enum": [
                              "facebook.post",
                              "facebook.search_ads",
                              "facebook.transcript",
                              "instagram.post",
                              "instagram.posts",
                              "instagram.profile",
                              "instagram.transcript",
                              "rumble.comments",
                              "rumble.post",
                              "rumble.posts",
                              "rumble.profile",
                              "rumble.search_posts",
                              "rumble.transcript",
                              "threads.profile",
                              "tiktok.comments",
                              "tiktok.post",
                              "tiktok.posts",
                              "tiktok.profile",
                              "tiktok.transcript",
                              "youtube.comments",
                              "youtube.post",
                              "youtube.posts",
                              "youtube.profile",
                              "youtube.transcript"
                            ],
                            "type": "string"
                          },
                          "error": {
                            "description": "Exactly the synchronous error object; null on success and for the job's own cancel or deadline.",
                            "properties": {
                              "charged": {
                                "description": "Whether the request was charged: always false, failed requests are free.",
                                "type": "boolean"
                              },
                              "code": {
                                "description": "Machine-readable error code (see the error codes list); stable.",
                                "type": "string"
                              },
                              "details": {
                                "additionalProperties": {},
                                "description": "The code's dynamic values (the error codes list documents each code's keys); {} when none.",
                                "type": "object"
                              },
                              "doc_url": {
                                "description": "URL of this code's documentation.",
                                "type": "string"
                              },
                              "message": {
                                "description": "What went wrong and how to fix it, for humans and agents; wording may change.",
                                "type": "string"
                              },
                              "param": {
                                "description": "The query parameter or header the error is about; null when it is not about one input.",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "remediation": {
                                "description": "What to do about this code, one sentence.",
                                "type": "string"
                              },
                              "request_id": {
                                "description": "Unique request ID; include it when contacting support.",
                                "type": "string"
                              },
                              "retryable": {
                                "description": "True when repeating the same request later may succeed (after details.retry_after when present).",
                                "type": "boolean"
                              },
                              "status": {
                                "description": "The HTTP status of the response, repeated for clients that only see the body.",
                                "type": "integer"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "request_id",
                              "status",
                              "retryable",
                              "param",
                              "remediation",
                              "doc_url",
                              "details",
                              "charged"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "object": {
                            "description": "Always job_result.",
                            "enum": [
                              "job_result"
                            ],
                            "type": "string"
                          },
                          "page_index": {
                            "description": "0 for a single-item endpoint and a list's first page; n for the list's page n+1.",
                            "type": "integer"
                          },
                          "result": {
                            "description": "Exactly the synchronous success envelope; null unless succeeded.",
                            "properties": {
                              "data": {
                                "description": "The endpoint's data: its resource, or a list page's items."
                              },
                              "meta": {
                                "properties": {
                                  "client_request_id": {
                                    "description": "Your x-client-request-id, echoed; null when you sent none.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "credits_charged": {
                                    "description": "Credits charged for this request (0 for errors and cache hits).",
                                    "type": "integer"
                                  },
                                  "credits_remaining": {
                                    "description": "Account balance after this request (the x-credits-remaining header); for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance; null when SocialTap could not read it.",
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "fetched_at": {
                                    "description": "When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).",
                                    "format": "date-time",
                                    "type": "string"
                                  },
                                  "input": {
                                    "description": "What the request's url or handle resolved to: kind, platform ID and canonical URL, so you can confirm what was fetched; null for searches.",
                                    "properties": {
                                      "id": {
                                        "description": "Platform-native ID of the item; null when it is only known after the fetch and the request failed.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "kind": {
                                        "description": "What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.",
                                        "type": "string"
                                      },
                                      "url": {
                                        "description": "Canonical URL of the item; null when unknown.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "kind",
                                      "id",
                                      "url"
                                    ],
                                    "type": [
                                      "object",
                                      "null"
                                    ]
                                  },
                                  "is_cached": {
                                    "description": "True when served from the cache (free); see max_age.",
                                    "type": "boolean"
                                  },
                                  "latency_ms": {
                                    "description": "Time SocialTap spent on the request, in milliseconds.",
                                    "type": "integer"
                                  },
                                  "mode": {
                                    "description": "live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added.",
                                    "enum": [
                                      "live",
                                      "test"
                                    ],
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "platform": {
                                    "description": "Platform ID of the endpoint (youtube, tiktok, …).",
                                    "type": "string"
                                  },
                                  "request_id": {
                                    "description": "Unique request ID; include it when contacting support.",
                                    "type": "string"
                                  },
                                  "source": {
                                    "description": "Which upstream strategy produced the data.",
                                    "type": "string"
                                  },
                                  "warnings": {
                                    "description": "Things to act on that did not fail the request: a deprecated endpoint, partial data. [] when none.",
                                    "items": {
                                      "properties": {
                                        "code": {
                                          "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                          "type": "string"
                                        },
                                        "doc_url": {
                                          "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                          "type": "string"
                                        },
                                        "fields": {
                                          "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                          "items": {
                                            "type": "string"
                                          },
                                          "type": "array"
                                        },
                                        "message": {
                                          "description": "What to do about it.",
                                          "type": "string"
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "message",
                                        "doc_url"
                                      ],
                                      "type": "object"
                                    },
                                    "type": "array"
                                  }
                                },
                                "required": [
                                  "request_id",
                                  "platform",
                                  "source",
                                  "is_cached",
                                  "credits_charged",
                                  "latency_ms",
                                  "fetched_at",
                                  "input",
                                  "credits_remaining",
                                  "client_request_id",
                                  "warnings",
                                  "mode"
                                ],
                                "type": "object"
                              },
                              "page": {
                                "description": "List endpoints only.",
                                "properties": {
                                  "end_reason": {
                                    "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                                    "enum": [
                                      "end",
                                      "platform_limit",
                                      "max_pages"
                                    ],
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "has_more": {
                                    "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                                    "type": "boolean"
                                  },
                                  "next_cursor": {
                                    "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "next_cursor_expires_at": {
                                    "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                                    "format": "date-time",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                },
                                "required": [
                                  "has_more",
                                  "next_cursor",
                                  "next_cursor_expires_at",
                                  "end_reason"
                                ],
                                "type": [
                                  "object",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "data",
                              "meta"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "The page's outcome; an item's status is its last result's. canceled and expired results carry no result (error says why when it is not the job's cancel or deadline).",
                            "enum": [
                              "succeeded",
                              "failed",
                              "canceled",
                              "expired"
                            ],
                            "type": "string"
                          },
                          "status_code": {
                            "description": "The HTTP status the synchronous request answered; null when it did not run.",
                            "type": [
                              "integer",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "object",
                          "custom_id",
                          "endpoint",
                          "page_index",
                          "status",
                          "status_code",
                          "result",
                          "error",
                          "completed_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "results_page": {
                      "description": "Only with results: the page object of results (continue on the results route).",
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Run many requests (or one long one) as a job",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "cancel_requested_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "credits": {
                          "properties": {
                            "charged": {
                              "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                              "type": "integer"
                            },
                            "max": {
                              "description": "max_credits: the most the job may spend.",
                              "type": "integer"
                            },
                            "reserved": {
                              "description": "Credits its running pages may still use (0 once the job ends).",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "max",
                            "reserved",
                            "charged"
                          ],
                          "type": "object"
                        },
                        "expires_at": {
                          "description": "The deadline: items not ended by then expire.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "finished_at": {
                          "description": "When the job ended; null while it runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "The job ID (job_…).",
                          "type": "string"
                        },
                        "max_age": {
                          "description": "The job's max_age; null when it accepts no cached results.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "metadata": {
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Your metadata; {} when none.",
                          "type": "object"
                        },
                        "object": {
                          "description": "Always job.",
                          "enum": [
                            "job"
                          ],
                          "type": "string"
                        },
                        "request_counts": {
                          "properties": {
                            "canceled": {
                              "type": "integer"
                            },
                            "expired": {
                              "type": "integer"
                            },
                            "failed": {
                              "type": "integer"
                            },
                            "queued": {
                              "description": "Not started.",
                              "type": "integer"
                            },
                            "running": {
                              "description": "Started (fetching, waiting for a retry or walking pages).",
                              "type": "integer"
                            },
                            "succeeded": {
                              "type": "integer"
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "total",
                            "queued",
                            "running",
                            "succeeded",
                            "failed",
                            "canceled",
                            "expired"
                          ],
                          "type": "object"
                        },
                        "results_expire_at": {
                          "description": "When results are deleted; null while the job runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url": {
                          "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url_expires_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "started_at": {
                          "description": "When the first item started; null before.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.",
                          "enum": [
                            "queued",
                            "running",
                            "canceling",
                            "completed",
                            "canceled",
                            "expired"
                          ],
                          "type": "string"
                        },
                        "webhook_url": {
                          "description": "The job's own webhook URL; null when none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "status",
                        "request_counts",
                        "credits",
                        "max_age",
                        "metadata",
                        "webhook_url",
                        "created_at",
                        "started_at",
                        "finished_at",
                        "cancel_requested_at",
                        "expires_at",
                        "results_url",
                        "results_url_expires_at",
                        "results_expire_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "results": {
                      "description": "Only on 200 from create with wait: the first page of results.",
                      "items": {
                        "properties": {
                          "completed_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "custom_id": {
                            "type": "string"
                          },
                          "endpoint": {
                            "enum": [
                              "facebook.post",
                              "facebook.search_ads",
                              "facebook.transcript",
                              "instagram.post",
                              "instagram.posts",
                              "instagram.profile",
                              "instagram.transcript",
                              "rumble.comments",
                              "rumble.post",
                              "rumble.posts",
                              "rumble.profile",
                              "rumble.search_posts",
                              "rumble.transcript",
                              "threads.profile",
                              "tiktok.comments",
                              "tiktok.post",
                              "tiktok.posts",
                              "tiktok.profile",
                              "tiktok.transcript",
                              "youtube.comments",
                              "youtube.post",
                              "youtube.posts",
                              "youtube.profile",
                              "youtube.transcript"
                            ],
                            "type": "string"
                          },
                          "error": {
                            "description": "Exactly the synchronous error object; null on success and for the job's own cancel or deadline.",
                            "properties": {
                              "charged": {
                                "description": "Whether the request was charged: always false, failed requests are free.",
                                "type": "boolean"
                              },
                              "code": {
                                "description": "Machine-readable error code (see the error codes list); stable.",
                                "type": "string"
                              },
                              "details": {
                                "additionalProperties": {},
                                "description": "The code's dynamic values (the error codes list documents each code's keys); {} when none.",
                                "type": "object"
                              },
                              "doc_url": {
                                "description": "URL of this code's documentation.",
                                "type": "string"
                              },
                              "message": {
                                "description": "What went wrong and how to fix it, for humans and agents; wording may change.",
                                "type": "string"
                              },
                              "param": {
                                "description": "The query parameter or header the error is about; null when it is not about one input.",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "remediation": {
                                "description": "What to do about this code, one sentence.",
                                "type": "string"
                              },
                              "request_id": {
                                "description": "Unique request ID; include it when contacting support.",
                                "type": "string"
                              },
                              "retryable": {
                                "description": "True when repeating the same request later may succeed (after details.retry_after when present).",
                                "type": "boolean"
                              },
                              "status": {
                                "description": "The HTTP status of the response, repeated for clients that only see the body.",
                                "type": "integer"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "request_id",
                              "status",
                              "retryable",
                              "param",
                              "remediation",
                              "doc_url",
                              "details",
                              "charged"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "object": {
                            "description": "Always job_result.",
                            "enum": [
                              "job_result"
                            ],
                            "type": "string"
                          },
                          "page_index": {
                            "description": "0 for a single-item endpoint and a list's first page; n for the list's page n+1.",
                            "type": "integer"
                          },
                          "result": {
                            "description": "Exactly the synchronous success envelope; null unless succeeded.",
                            "properties": {
                              "data": {
                                "description": "The endpoint's data: its resource, or a list page's items."
                              },
                              "meta": {
                                "properties": {
                                  "client_request_id": {
                                    "description": "Your x-client-request-id, echoed; null when you sent none.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "credits_charged": {
                                    "description": "Credits charged for this request (0 for errors and cache hits).",
                                    "type": "integer"
                                  },
                                  "credits_remaining": {
                                    "description": "Account balance after this request (the x-credits-remaining header); for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance; null when SocialTap could not read it.",
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "fetched_at": {
                                    "description": "When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).",
                                    "format": "date-time",
                                    "type": "string"
                                  },
                                  "input": {
                                    "description": "What the request's url or handle resolved to: kind, platform ID and canonical URL, so you can confirm what was fetched; null for searches.",
                                    "properties": {
                                      "id": {
                                        "description": "Platform-native ID of the item; null when it is only known after the fetch and the request failed.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "kind": {
                                        "description": "What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.",
                                        "type": "string"
                                      },
                                      "url": {
                                        "description": "Canonical URL of the item; null when unknown.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "kind",
                                      "id",
                                      "url"
                                    ],
                                    "type": [
                                      "object",
                                      "null"
                                    ]
                                  },
                                  "is_cached": {
                                    "description": "True when served from the cache (free); see max_age.",
                                    "type": "boolean"
                                  },
                                  "latency_ms": {
                                    "description": "Time SocialTap spent on the request, in milliseconds.",
                                    "type": "integer"
                                  },
                                  "mode": {
                                    "description": "live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added.",
                                    "enum": [
                                      "live",
                                      "test"
                                    ],
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "platform": {
                                    "description": "Platform ID of the endpoint (youtube, tiktok, …).",
                                    "type": "string"
                                  },
                                  "request_id": {
                                    "description": "Unique request ID; include it when contacting support.",
                                    "type": "string"
                                  },
                                  "source": {
                                    "description": "Which upstream strategy produced the data.",
                                    "type": "string"
                                  },
                                  "warnings": {
                                    "description": "Things to act on that did not fail the request: a deprecated endpoint, partial data. [] when none.",
                                    "items": {
                                      "properties": {
                                        "code": {
                                          "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                          "type": "string"
                                        },
                                        "doc_url": {
                                          "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                          "type": "string"
                                        },
                                        "fields": {
                                          "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                          "items": {
                                            "type": "string"
                                          },
                                          "type": "array"
                                        },
                                        "message": {
                                          "description": "What to do about it.",
                                          "type": "string"
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "message",
                                        "doc_url"
                                      ],
                                      "type": "object"
                                    },
                                    "type": "array"
                                  }
                                },
                                "required": [
                                  "request_id",
                                  "platform",
                                  "source",
                                  "is_cached",
                                  "credits_charged",
                                  "latency_ms",
                                  "fetched_at",
                                  "input",
                                  "credits_remaining",
                                  "client_request_id",
                                  "warnings",
                                  "mode"
                                ],
                                "type": "object"
                              },
                              "page": {
                                "description": "List endpoints only.",
                                "properties": {
                                  "end_reason": {
                                    "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                                    "enum": [
                                      "end",
                                      "platform_limit",
                                      "max_pages"
                                    ],
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "has_more": {
                                    "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                                    "type": "boolean"
                                  },
                                  "next_cursor": {
                                    "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "next_cursor_expires_at": {
                                    "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                                    "format": "date-time",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                },
                                "required": [
                                  "has_more",
                                  "next_cursor",
                                  "next_cursor_expires_at",
                                  "end_reason"
                                ],
                                "type": [
                                  "object",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "data",
                              "meta"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "The page's outcome; an item's status is its last result's. canceled and expired results carry no result (error says why when it is not the job's cancel or deadline).",
                            "enum": [
                              "succeeded",
                              "failed",
                              "canceled",
                              "expired"
                            ],
                            "type": "string"
                          },
                          "status_code": {
                            "description": "The HTTP status the synchronous request answered; null when it did not run.",
                            "type": [
                              "integer",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "object",
                          "custom_id",
                          "endpoint",
                          "page_index",
                          "status",
                          "status_code",
                          "result",
                          "error",
                          "completed_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "results_page": {
                      "description": "Only with results: the page object of results (continue on the results route).",
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Accepted: the job continues in the background (poll its Location, free).",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "location": {
                "$ref": "#/components/headers/location"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Run many requests (or one long one) as a job",
        "tags": [
          "Jobs"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "jobs"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "description": "The job's status, per-state request counts and credits. Free: poll it, or long-poll with `wait`.\n\n**Auth:** an API key with the `jobs` scope, or the dashboard session.\n\n**Test mode:** A test key's job runs every item in test mode: each gets its endpoint's test-mode answer (recorded responses, magic inputs), free; nothing is held or charged. A test key sees test jobs only.",
        "operationId": "jobs.get",
        "parameters": [
          {
            "description": "Job ID (job_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Seconds to wait for the job to end before answering (a long poll): the answer is the job as it is then.",
            "in": "query",
            "name": "wait",
            "schema": {
              "maximum": 60,
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "cancel_requested_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "credits": {
                          "properties": {
                            "charged": {
                              "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                              "type": "integer"
                            },
                            "max": {
                              "description": "max_credits: the most the job may spend.",
                              "type": "integer"
                            },
                            "reserved": {
                              "description": "Credits its running pages may still use (0 once the job ends).",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "max",
                            "reserved",
                            "charged"
                          ],
                          "type": "object"
                        },
                        "expires_at": {
                          "description": "The deadline: items not ended by then expire.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "finished_at": {
                          "description": "When the job ended; null while it runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "The job ID (job_…).",
                          "type": "string"
                        },
                        "max_age": {
                          "description": "The job's max_age; null when it accepts no cached results.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "metadata": {
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Your metadata; {} when none.",
                          "type": "object"
                        },
                        "object": {
                          "description": "Always job.",
                          "enum": [
                            "job"
                          ],
                          "type": "string"
                        },
                        "request_counts": {
                          "properties": {
                            "canceled": {
                              "type": "integer"
                            },
                            "expired": {
                              "type": "integer"
                            },
                            "failed": {
                              "type": "integer"
                            },
                            "queued": {
                              "description": "Not started.",
                              "type": "integer"
                            },
                            "running": {
                              "description": "Started (fetching, waiting for a retry or walking pages).",
                              "type": "integer"
                            },
                            "succeeded": {
                              "type": "integer"
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "total",
                            "queued",
                            "running",
                            "succeeded",
                            "failed",
                            "canceled",
                            "expired"
                          ],
                          "type": "object"
                        },
                        "results_expire_at": {
                          "description": "When results are deleted; null while the job runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url": {
                          "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url_expires_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "started_at": {
                          "description": "When the first item started; null before.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.",
                          "enum": [
                            "queued",
                            "running",
                            "canceling",
                            "completed",
                            "canceled",
                            "expired"
                          ],
                          "type": "string"
                        },
                        "webhook_url": {
                          "description": "The job's own webhook URL; null when none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "status",
                        "request_counts",
                        "credits",
                        "max_age",
                        "metadata",
                        "webhook_url",
                        "created_at",
                        "started_at",
                        "finished_at",
                        "cancel_requested_at",
                        "expires_at",
                        "results_url",
                        "results_url_expires_at",
                        "results_expire_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get a job (free to poll)",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "job_not_found": {
                    "$ref": "#/components/examples/job_not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`job_not_found`: No job with this ID exists for the account: unknown, or past its retention. Check the job ID; finished jobs are kept for a limited time.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Get a job (free to poll)",
        "tags": [
          "Jobs"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "jobs"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/jobs/{id}/cancel": {
      "post": {
        "description": "Stops the job: items not started become `canceled` (free); items already running finish and are charged. The job is `canceling` until they do, then `canceled`. Canceling an ended job changes nothing. Free.\n\n**Auth:** an API key with the `jobs` scope, or the dashboard session.\n\n**Test mode:** A test key's job runs every item in test mode: each gets its endpoint's test-mode answer (recorded responses, magic inputs), free; nothing is held or charged. A test key sees test jobs only.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "jobs.cancel",
        "parameters": [
          {
            "description": "Job ID (job_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "cancel_requested_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "credits": {
                          "properties": {
                            "charged": {
                              "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                              "type": "integer"
                            },
                            "max": {
                              "description": "max_credits: the most the job may spend.",
                              "type": "integer"
                            },
                            "reserved": {
                              "description": "Credits its running pages may still use (0 once the job ends).",
                              "type": "integer"
                            }
                          },
                          "required": [
                            "max",
                            "reserved",
                            "charged"
                          ],
                          "type": "object"
                        },
                        "expires_at": {
                          "description": "The deadline: items not ended by then expire.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "finished_at": {
                          "description": "When the job ended; null while it runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "id": {
                          "description": "The job ID (job_…).",
                          "type": "string"
                        },
                        "max_age": {
                          "description": "The job's max_age; null when it accepts no cached results.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "metadata": {
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Your metadata; {} when none.",
                          "type": "object"
                        },
                        "object": {
                          "description": "Always job.",
                          "enum": [
                            "job"
                          ],
                          "type": "string"
                        },
                        "request_counts": {
                          "properties": {
                            "canceled": {
                              "type": "integer"
                            },
                            "expired": {
                              "type": "integer"
                            },
                            "failed": {
                              "type": "integer"
                            },
                            "queued": {
                              "description": "Not started.",
                              "type": "integer"
                            },
                            "running": {
                              "description": "Started (fetching, waiting for a retry or walking pages).",
                              "type": "integer"
                            },
                            "succeeded": {
                              "type": "integer"
                            },
                            "total": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "total",
                            "queued",
                            "running",
                            "succeeded",
                            "failed",
                            "canceled",
                            "expired"
                          ],
                          "type": "object"
                        },
                        "results_expire_at": {
                          "description": "When results are deleted; null while the job runs.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url": {
                          "description": "Every result as JSON Lines (one JobResult per line), signed: works without the API key until results_url_expires_at. Null until the job ends and after results_expire_at.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "results_url_expires_at": {
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "started_at": {
                          "description": "When the first item started; null before.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "description": "queued: nothing started yet. running. canceling: canceled, running items finishing. completed: every item ended (check request_counts: there is no job-level failure). canceled. expired: the deadline passed; unfinished items expired.",
                          "enum": [
                            "queued",
                            "running",
                            "canceling",
                            "completed",
                            "canceled",
                            "expired"
                          ],
                          "type": "string"
                        },
                        "webhook_url": {
                          "description": "The job's own webhook URL; null when none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "status",
                        "request_counts",
                        "credits",
                        "max_age",
                        "metadata",
                        "webhook_url",
                        "created_at",
                        "started_at",
                        "finished_at",
                        "cancel_requested_at",
                        "expires_at",
                        "results_url",
                        "results_url_expires_at",
                        "results_expire_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Cancel a job",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "job_not_found": {
                    "$ref": "#/components/examples/job_not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`job_not_found`: No job with this ID exists for the account: unknown, or past its retention. Check the job ID; finished jobs are kept for a limited time.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Cancel a job",
        "tags": [
          "Jobs"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "jobs"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/jobs/{id}/results": {
      "get": {
        "description": "The job's results in the order they completed, cursor-paged: one per page an item fetched (a single-item endpoint has one page), and one with the item's final status when it ended without a result (canceled, expired). `result` is exactly the synchronous response's envelope, `error` exactly its error object. Results of a running job can be read as they arrive: keep the last `page.next_cursor` and continue from it. Kept `results_retention_s` (7 days) after the job ends. Free.\n\n**Auth:** an API key with the `jobs` scope, or the dashboard session.\n\n**Test mode:** A test key's job runs every item in test mode: each gets its endpoint's test-mode answer (recorded responses, magic inputs), free; nothing is held or charged. A test key sees test jobs only.",
        "operationId": "jobs.results.list",
        "parameters": [
          {
            "description": "Job ID (job_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only results in this status (e.g. failed, to resubmit them).",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "succeeded",
                "failed",
                "canceled",
                "expired"
              ],
              "type": "string"
            }
          },
          {
            "description": "Results per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page; omit to start from the first result.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "completed_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "custom_id": {
                            "type": "string"
                          },
                          "endpoint": {
                            "enum": [
                              "facebook.post",
                              "facebook.search_ads",
                              "facebook.transcript",
                              "instagram.post",
                              "instagram.posts",
                              "instagram.profile",
                              "instagram.transcript",
                              "rumble.comments",
                              "rumble.post",
                              "rumble.posts",
                              "rumble.profile",
                              "rumble.search_posts",
                              "rumble.transcript",
                              "threads.profile",
                              "tiktok.comments",
                              "tiktok.post",
                              "tiktok.posts",
                              "tiktok.profile",
                              "tiktok.transcript",
                              "youtube.comments",
                              "youtube.post",
                              "youtube.posts",
                              "youtube.profile",
                              "youtube.transcript"
                            ],
                            "type": "string"
                          },
                          "error": {
                            "description": "Exactly the synchronous error object; null on success and for the job's own cancel or deadline.",
                            "properties": {
                              "charged": {
                                "description": "Whether the request was charged: always false, failed requests are free.",
                                "type": "boolean"
                              },
                              "code": {
                                "description": "Machine-readable error code (see the error codes list); stable.",
                                "type": "string"
                              },
                              "details": {
                                "additionalProperties": {},
                                "description": "The code's dynamic values (the error codes list documents each code's keys); {} when none.",
                                "type": "object"
                              },
                              "doc_url": {
                                "description": "URL of this code's documentation.",
                                "type": "string"
                              },
                              "message": {
                                "description": "What went wrong and how to fix it, for humans and agents; wording may change.",
                                "type": "string"
                              },
                              "param": {
                                "description": "The query parameter or header the error is about; null when it is not about one input.",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "remediation": {
                                "description": "What to do about this code, one sentence.",
                                "type": "string"
                              },
                              "request_id": {
                                "description": "Unique request ID; include it when contacting support.",
                                "type": "string"
                              },
                              "retryable": {
                                "description": "True when repeating the same request later may succeed (after details.retry_after when present).",
                                "type": "boolean"
                              },
                              "status": {
                                "description": "The HTTP status of the response, repeated for clients that only see the body.",
                                "type": "integer"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "request_id",
                              "status",
                              "retryable",
                              "param",
                              "remediation",
                              "doc_url",
                              "details",
                              "charged"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "object": {
                            "description": "Always job_result.",
                            "enum": [
                              "job_result"
                            ],
                            "type": "string"
                          },
                          "page_index": {
                            "description": "0 for a single-item endpoint and a list's first page; n for the list's page n+1.",
                            "type": "integer"
                          },
                          "result": {
                            "description": "Exactly the synchronous success envelope; null unless succeeded.",
                            "properties": {
                              "data": {
                                "description": "The endpoint's data: its resource, or a list page's items."
                              },
                              "meta": {
                                "properties": {
                                  "client_request_id": {
                                    "description": "Your x-client-request-id, echoed; null when you sent none.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "credits_charged": {
                                    "description": "Credits charged for this request (0 for errors and cache hits).",
                                    "type": "integer"
                                  },
                                  "credits_remaining": {
                                    "description": "Account balance after this request (the x-credits-remaining header); for a busy account an estimate that may not yet subtract concurrent requests (about a second of usage), never below the real balance; null when SocialTap could not read it.",
                                    "type": [
                                      "integer",
                                      "null"
                                    ]
                                  },
                                  "fetched_at": {
                                    "description": "When the data was fetched from the platform, RFC 3339 UTC (older than the request for cache hits).",
                                    "format": "date-time",
                                    "type": "string"
                                  },
                                  "input": {
                                    "description": "What the request's url or handle resolved to: kind, platform ID and canonical URL, so you can confirm what was fetched; null for searches.",
                                    "properties": {
                                      "id": {
                                        "description": "Platform-native ID of the item; null when it is only known after the fetch and the request failed.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      },
                                      "kind": {
                                        "description": "What the input points to (profile, video, post, …). New values may be added; treat unknown values as other.",
                                        "type": "string"
                                      },
                                      "url": {
                                        "description": "Canonical URL of the item; null when unknown.",
                                        "type": [
                                          "string",
                                          "null"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "kind",
                                      "id",
                                      "url"
                                    ],
                                    "type": [
                                      "object",
                                      "null"
                                    ]
                                  },
                                  "is_cached": {
                                    "description": "True when served from the cache (free); see max_age.",
                                    "type": "boolean"
                                  },
                                  "latency_ms": {
                                    "description": "Time SocialTap spent on the request, in milliseconds.",
                                    "type": "integer"
                                  },
                                  "mode": {
                                    "description": "live, or test for a test key's answer: a recorded response (fixture), free and deterministic; null when SocialTap could not tell. New values may be added.",
                                    "enum": [
                                      "live",
                                      "test"
                                    ],
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "platform": {
                                    "description": "Platform ID of the endpoint (youtube, tiktok, …).",
                                    "type": "string"
                                  },
                                  "request_id": {
                                    "description": "Unique request ID; include it when contacting support.",
                                    "type": "string"
                                  },
                                  "source": {
                                    "description": "Which upstream strategy produced the data.",
                                    "type": "string"
                                  },
                                  "warnings": {
                                    "description": "Things to act on that did not fail the request: a deprecated endpoint, partial data. [] when none.",
                                    "items": {
                                      "properties": {
                                        "code": {
                                          "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                          "type": "string"
                                        },
                                        "doc_url": {
                                          "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                          "type": "string"
                                        },
                                        "fields": {
                                          "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                          "items": {
                                            "type": "string"
                                          },
                                          "type": "array"
                                        },
                                        "message": {
                                          "description": "What to do about it.",
                                          "type": "string"
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "message",
                                        "doc_url"
                                      ],
                                      "type": "object"
                                    },
                                    "type": "array"
                                  }
                                },
                                "required": [
                                  "request_id",
                                  "platform",
                                  "source",
                                  "is_cached",
                                  "credits_charged",
                                  "latency_ms",
                                  "fetched_at",
                                  "input",
                                  "credits_remaining",
                                  "client_request_id",
                                  "warnings",
                                  "mode"
                                ],
                                "type": "object"
                              },
                              "page": {
                                "description": "List endpoints only.",
                                "properties": {
                                  "end_reason": {
                                    "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                                    "enum": [
                                      "end",
                                      "platform_limit",
                                      "max_pages"
                                    ],
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "has_more": {
                                    "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                                    "type": "boolean"
                                  },
                                  "next_cursor": {
                                    "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "next_cursor_expires_at": {
                                    "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                                    "format": "date-time",
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                },
                                "required": [
                                  "has_more",
                                  "next_cursor",
                                  "next_cursor_expires_at",
                                  "end_reason"
                                ],
                                "type": [
                                  "object",
                                  "null"
                                ]
                              }
                            },
                            "required": [
                              "data",
                              "meta"
                            ],
                            "type": [
                              "object",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "The page's outcome; an item's status is its last result's. canceled and expired results carry no result (error says why when it is not the job's cancel or deadline).",
                            "enum": [
                              "succeeded",
                              "failed",
                              "canceled",
                              "expired"
                            ],
                            "type": "string"
                          },
                          "status_code": {
                            "description": "The HTTP status the synchronous request answered; null when it did not run.",
                            "type": [
                              "integer",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "object",
                          "custom_id",
                          "endpoint",
                          "page_index",
                          "status",
                          "status_code",
                          "result",
                          "error",
                          "completed_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List a job's results as they complete",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "job_not_found": {
                    "$ref": "#/components/examples/job_not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`job_not_found`: No job with this ID exists for the account: unknown, or past its retention. Check the job ID; finished jobs are kept for a limited time.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List a job's results as they complete",
        "tags": [
          "Jobs"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "jobs"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/jobs/{id}/results.jsonl": {
      "get": {
        "description": "The job's `results_url`: every result as JSON Lines (one JobResult object per line, in completion order), streamed. The URL is signed: it needs no API key and works until `results_url_expires_at`; GET the job again for a fresh one. Free.\n\n**Auth:** none: the signed URL is the credential.",
        "operationId": "jobs.results.download",
        "parameters": [
          {
            "description": "Job ID (job_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Set by SocialTap: the job's account (and mode).",
            "in": "query",
            "name": "account",
            "schema": {
              "maxLength": 100,
              "type": "string"
            }
          },
          {
            "description": "Set by SocialTap: when the URL stops working (Unix seconds).",
            "in": "query",
            "name": "expires",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Set by SocialTap: the URL's signature.",
            "in": "query",
            "name": "signature",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/jsonl": {
                "schema": {
                  "description": "One JSON object per line, each a JobResult:\n\n",
                  "type": "string"
                }
              }
            },
            "description": "Download every result of a job (JSON Lines)",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "job_not_found": {
                    "$ref": "#/components/examples/job_not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`job_not_found`: No job with this ID exists for the account: unknown, or past its retention. Check the job ID; finished jobs are kept for a limited time.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [],
        "summary": "Download every result of a job (JSON Lines)",
        "tags": [
          "Jobs"
        ],
        "x-socialtap-auth": {
          "auth": "none",
          "scope": ""
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [],
          "retry_after_header": "retry-after",
          "retryable_codes": []
        }
      }
    },
    "/v1/rumble/comments": {
      "get": {
        "description": "Returns the public comments of a Rumble video, short or live stream, replies included, a page at a time: text, the commenter's username, name, avatar and badges, posting time, likes and dislikes, reply count, the comment each reply answers, a permalink, and whether the video's own channel wrote it. Sort newest first (the default, which also supports since and until) or in Rumble's Sort by likes order, and follow page.next_cursor for more. Accepts every Rumble video link form, embed links included, or a bare video ID.\n\nReturns `{data, page, meta}`: `data` holds up to 500 `Comment` items (the shared schema, the same on every platform), newest first with sort=newest (the default), Rumble's Sort by likes order of comments, each followed by its replies with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit (api) per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/rumble/comments/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/rumble/comments/"
        },
        "operationId": "rumble.comments.list",
        "parameters": [
          {
            "description": "Rumble video, short or live stream URL (rumble.com/v…-title.html, /shorts/v…, /share/v…, /embed/v…/) or a video ID (v…).",
            "example": "https://rumble.com/shorts/v7h29za",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Rumble video, short or live stream URL (rumble.com/v…-title.html, /shorts/v…, /share/v…, /embed/v…/) or a video ID (v…).",
              "examples": [
                "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Order of the results. newest (default): every comment and reply, newest first. popular: Rumble's Sort by likes order of comments, each followed by its replies.",
            "example": "",
            "in": "query",
            "name": "sort",
            "schema": {
              "default": "newest",
              "description": "Order of the results. newest (default): every comment and reply, newest first. popular: Rumble's Sort by likes order of comments, each followed by its replies.",
              "enum": [
                "newest",
                "popular"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Compared with published_at, which Rumble shows to the minute. Replies count as items: on newest the walk stops at the first comment or reply older than since.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Compared with published_at, which Rumble shows to the minute. Replies count as items: on newest the walk stops at the first comment or reply older than since.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 500,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 500,
              "maximum": 500,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [
                            "published_at"
                          ],
                          "author": {
                            "avatar_url": "https://hugh.cdn.rumble.cloud/video/z0/e/b/M/g/ebMgr.asF.1-4qu5ac-tnkdxy.jpeg",
                            "display_name": "inshallakhan",
                            "id": null,
                            "is_verified": false,
                            "url": "https://rumble.com/user/inshallakhan",
                            "username": "user/inshallakhan"
                          },
                          "edited_at": null,
                          "id": "620403472",
                          "is_by_post_author": false,
                          "is_edited": null,
                          "is_liked_by_author": null,
                          "is_pinned": null,
                          "metrics": {
                            "like_count": 0,
                            "reply_count": 0
                          },
                          "parent_id": null,
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_badges": [],
                              "dislike_count": 0
                            }
                          },
                          "post_id": "v7h29za",
                          "published_at": "2026-10-23T03:31:00Z",
                          "text": "oh 😯😯",
                          "unknown_fields": [],
                          "url": "https://rumble.com/shorts/v7h29za#comment-620403472"
                        },
                        {
                          "approximate_fields": [
                            "published_at"
                          ],
                          "author": {
                            "avatar_url": "https://hugh.cdn.rumble.cloud/video/z0/C/E/l/b/CElbr.asF-4pzq1o-ti0cx0.jpeg",
                            "display_name": "CassandraB89",
                            "id": null,
                            "is_verified": false,
                            "url": "https://rumble.com/user/CassandraB89",
                            "username": "user/CassandraB89"
                          },
                          "edited_at": null,
                          "id": "620356964",
                          "is_by_post_author": false,
                          "is_edited": null,
                          "is_liked_by_author": null,
                          "is_pinned": null,
                          "metrics": {
                            "like_count": 0,
                            "reply_count": 0
                          },
                          "parent_id": null,
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_badges": [],
                              "dislike_count": 0
                            }
                          },
                          "post_id": "v7h29za",
                          "published_at": "2026-10-22T13:01:00Z",
                          "text": "🐈👌🏻🧡",
                          "unknown_fields": [],
                          "url": "https://rumble.com/shorts/v7h29za#comment-620356964"
                        },
                        {
                          "approximate_fields": [
                            "published_at"
                          ],
                          "author": {
                            "avatar_url": null,
                            "display_name": "SkyeWalker0504",
                            "id": null,
                            "is_verified": false,
                            "url": "https://rumble.com/user/SkyeWalker0504",
                            "username": "user/SkyeWalker0504"
                          },
                          "edited_at": null,
                          "id": "620301964",
                          "is_by_post_author": false,
                          "is_edited": null,
                          "is_liked_by_author": null,
                          "is_pinned": null,
                          "metrics": {
                            "like_count": 1,
                            "reply_count": 0
                          },
                          "parent_id": null,
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_badges": [],
                              "dislike_count": 0
                            }
                          },
                          "post_id": "v7h29za",
                          "published_at": "2026-10-21T15:29:00Z",
                          "text": "Looks like a Minecraft cat.",
                          "unknown_fields": [],
                          "url": "https://rumble.com/shorts/v7h29za#comment-620301964"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "rumble",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "v7h29za",
                          "url": "https://rumble.com/v7h29za"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": false,
                        "next_cursor": null,
                        "next_cursor_expires_at": null,
                        "end_reason": "end"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RumbleCommentsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Comments and replies of a Rumble video",
        "tags": [
          "Rumble"
        ],
        "x-socialtap-endpoint": "rumble.comments",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 86400,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "newest first",
          "orders": {
            "newest": "newest first",
            "popular": "Rumble's Sort by likes order of comments, each followed by its replies"
          },
          "page_max": 500,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "api"
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "comment",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/rumble/post": {
      "get": {
        "description": "Returns a public Rumble video, short or live stream: title, full description, publish time, duration, thumbnail, the channel with its avatar, badge and follower count, views, likes and dislikes, Rumble's categories and tags, every video and audio file with its size, the caption tracks, and for live streams whether they are on air, when they started or are scheduled, and how many people are watching. Accepts every Rumble video link form, embed links included, or a bare video ID.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/rumble/post/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/rumble/post/"
        },
        "operationId": "rumble.post.get",
        "parameters": [
          {
            "description": "Rumble video, short or live stream URL (rumble.com/v…-title.html, /shorts/v…, /share/v…, /embed/v…/) or a video ID (v…).",
            "example": "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Rumble video, short or live stream URL (rumble.com/v…-title.html, /shorts/v…, /share/v…, /embed/v…/) or a video ID (v…).",
              "examples": [
                "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [
                          "platform_specific.rumble.author_follower_count"
                        ],
                        "author": {
                          "avatar_url": "https://hugh.cdn.rumble.cloud/video/z8/g/D/5/d/gD5da.baa.2-GGreenwald-rml416.png",
                          "display_name": "Glenn Greenwald",
                          "id": "_c1021766",
                          "is_verified": true,
                          "url": "https://rumble.com/c/GGreenwald",
                          "username": "GGreenwald"
                        },
                        "coauthors": [],
                        "duration_ms": 1678000,
                        "hashtags": [],
                        "id": "v79xhhm",
                        "is_nsfw": null,
                        "is_pinned": null,
                        "is_sponsored": null,
                        "language": null,
                        "media": [
                          {
                            "alt_text": null,
                            "duration_ms": 1678000,
                            "expires_at": null,
                            "height": 1080,
                            "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/1/k/V/p/o/kVpoA.qR4e-small-DISCOVERY-Why-Glenn-WANTS-I..jpg",
                            "type": "video",
                            "url": "https://rumble.com/hls-vod/vjXafkcCce8/playlist.m3u8",
                            "width": 1920
                          }
                        ],
                        "mentions": [],
                        "metrics": {
                          "comment_count": 22,
                          "like_count": 209,
                          "quote_count": null,
                          "repost_count": null,
                          "save_count": null,
                          "share_count": null,
                          "view_count": 25366
                        },
                        "platform": "rumble",
                        "platform_specific": {
                          "rumble": {
                            "author_follower_count": 584000,
                            "caption_tracks": [
                              {
                                "is_auto_generated": true,
                                "label": "English (auto)",
                                "language": "en",
                                "url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/11/k/V/p/o/kVpoA.fn8Si.1.vtt"
                              }
                            ],
                            "category": "News",
                            "concurrent_viewer_count": null,
                            "dislike_count": 4,
                            "embed_id": "v77qthe",
                            "embed_url": "https://rumble.com/embed/v77qthe/",
                            "files": [
                              {
                                "bitrate_kbps": 2142,
                                "format": "tar",
                                "height": 720,
                                "kind": "video",
                                "size_bytes": 449566720,
                                "url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/2/k/V/p/o/kVpoA.gaa.tar?r_file=chunklist.m3u8&r_type=application%2Fvnd.apple.mpegurl&r_range=449539072-449555872",
                                "width": 1280
                              },
                              {
                                "bitrate_kbps": 1059,
                                "format": "tar",
                                "height": 480,
                                "kind": "video",
                                "size_bytes": 222300160,
                                "url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/2/k/V/p/o/kVpoA.caa.tar?r_file=chunklist.m3u8&r_type=application%2Fvnd.apple.mpegurl&r_range=222280704-222297420",
                                "width": 854
                              },
                              {
                                "bitrate_kbps": 679,
                                "format": "tar",
                                "height": 360,
                                "kind": "video",
                                "size_bytes": 142510080,
                                "url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/2/k/V/p/o/kVpoA.baa.tar?r_file=chunklist.m3u8&r_type=application%2Fvnd.apple.mpegurl&r_range=142485504-142502129",
                                "width": 640
                              }
                            ],
                            "is_age_restricted": null,
                            "is_live_now": false,
                            "keywords": [],
                            "live_started_at": null,
                            "numeric_id": "436271810",
                            "scheduled_start_at": null,
                            "secondary_category": "Politics"
                          }
                        },
                        "platform_type": "video",
                        "published_at": "2026-05-16T11:31:27Z",
                        "text": "Follow Glenn Greenwald's writing and other journalism at Substack, where you can become a member: https://greenwald.substack.com/\n\nAll videos now available as a podcast! Find full episodes here: https://linktr.ee/systemupdate_\n\nFollow Glenn:\nTwitter: https://twitter.com/ggreenwal…",
                        "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/1/k/V/p/o/kVpoA.qR4e-small-DISCOVERY-Why-Glenn-WANTS-I..jpg",
                        "title": "DISCOVERY: Why Glenn WANTS Israel to Sue The New York Times",
                        "type": "video",
                        "unknown_fields": [],
                        "url": "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "rumble",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "v79xhhm",
                          "url": "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RumblePostResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Rumble video, short or live stream with votes and files",
        "tags": [
          "Rumble"
        ],
        "x-socialtap-endpoint": "rumble.post",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/rumble/posts": {
      "get": {
        "description": "Returns the public uploads of a Rumble channel or user a page at a time: its videos, its shorts or its live streams (on air now, scheduled and past), newest or most viewed first. Each carries its link, title, thumbnail, exact upload time and length, exact views, likes, dislikes, comments and reposts, the video file, the channel with its exact follower count and badge, and for streams whether they are on air, the viewer count and when they started or are due. Accepts a channel or user name, any channel or user link, or a channel's ID.\n\nReturns `{data, page, meta}`: `data` holds up to 25 `Post` items (the shared schema, the same on every platform), Rumble's upload order (newest uploads first, not strictly by published_at) with sort=newest (the default), Rumble's View count order (most viewed first) with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/rumble/posts/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/rumble/posts/"
        },
        "operationId": "rumble.posts.list",
        "parameters": [
          {
            "description": "Rumble channel or user: a bare name (Bongino: a channel, else the user of that name), c/<name> for a channel or user/<name> for a user, any channel or user link with any tab after it (rumble.com/c/Bongino, rumble.com/c/Bongino/shorts, rumble.com/user/vivafrei/livestreams, the root rumble.com/Bongino link), or a channel's id as this API returns it (_c276782) or its c/c-<channel id> name. A user's _u… id is refused: Rumble's public pages cannot look a user up by ID, so send its name. Names are case-insensitive.",
            "example": "Bongino",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "Rumble channel or user: a bare name (Bongino: a channel, else the user of that name), c/<name> for a channel or user/<name> for a user, any channel or user link with any tab after it (rumble.com/c/Bongino, rumble.com/c/Bongino/shorts, rumble.com/user/vivafrei/livestreams, the root rumble.com/Bongino link), or a channel's id as this API returns it (_c276782) or its c/c-<channel id> name. A user's _u… id is refused: Rumble's public pages cannot look a user up by ID, so send its name. Names are case-insensitive.",
              "examples": [
                "Bongino"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "The tab to list: videos (default), shorts or live (Rumble's Livestreams tab: streams on air now, scheduled ones and past ones). A user's tabs include the videos of the channels it owns.",
            "example": "live",
            "in": "query",
            "name": "tab",
            "schema": {
              "description": "The tab to list: videos (default), shorts or live (Rumble's Livestreams tab: streams on air now, scheduled ones and past ones). A user's tabs include the videos of the channels it owns.",
              "enum": [
                "videos",
                "shorts",
                "live"
              ],
              "examples": [
                "live"
              ],
              "type": "string"
            }
          },
          {
            "description": "Order of the results. newest (default): Rumble's upload order, newest uploads first (Rumble's own order, not strictly by published_at: older uploads can sit among newer ones). popular: Rumble's View count order (most viewed first).",
            "example": "",
            "in": "query",
            "name": "sort",
            "schema": {
              "default": "newest",
              "description": "Order of the results. newest (default): Rumble's upload order, newest uploads first (Rumble's own order, not strictly by published_at: older uploads can sit among newer ones). popular: Rumble's View count order (most viewed first).",
              "enum": [
                "newest",
                "popular"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only posts published at or after this time. Neither sort is strictly by date, so since filters every page instead of ending the walk at the first older post: the walk ends after a few pages in a row with nothing in the window, and those pages are free.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Only posts published at or after this time. Neither sort is strictly by date, so since filters every page instead of ending the walk at the first older post: the walk ends after a few pages in a row with nothing in the window, and those pages are free.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only posts published before this time; filters every page, like since.",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Only posts published before this time; filters every page, like since.",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only short videos (Rumble's Under 4 minutes) or long ones (Over 20 minutes); any length when omitted. Not with tab=shorts.",
            "example": "long",
            "in": "query",
            "name": "duration",
            "schema": {
              "description": "Only short videos (Rumble's Under 4 minutes) or long ones (Over 20 minutes); any length when omitted. Not with tab=shorts.",
              "enum": [
                "short",
                "long"
              ],
              "examples": [
                "long"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 25,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 25,
              "maximum": 25,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://hugh.cdn.rumble.cloud/video/z8/U/K/d/b/UKdba.baa.4-bongino-t8rqq7.jpeg",
                            "display_name": "The Dan Bongino Show",
                            "id": "_c276782",
                            "is_verified": true,
                            "url": "https://rumble.com/c/bongino",
                            "username": "bongino"
                          },
                          "coauthors": [],
                          "duration_ms": 3233000,
                          "hashtags": [],
                          "id": "v7haadi",
                          "is_nsfw": false,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 3233000,
                              "expires_at": null,
                              "height": 1080,
                              "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/25/s8/1/g/a/y/9/gay9A.OvCc-small-Bongino-Weekend-Report-Week..jpg",
                              "type": "video",
                              "url": "https://hugh.cdn.rumble.cloud/video/fww1/25/s8/2/g/a/y/9/gay9A.haa.mp4",
                              "width": 1920
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 80,
                            "like_count": 1182,
                            "quote_count": null,
                            "repost_count": 3,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 207825
                          },
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_follower_count": 3673478,
                              "caption_tracks": [],
                              "category": null,
                              "concurrent_viewer_count": null,
                              "dislike_count": 13,
                              "embed_id": "v7f3xg0",
                              "embed_url": "https://rumble.com/embed/v7f3xg0/",
                              "files": [],
                              "is_age_restricted": false,
                              "is_live_now": false,
                              "keywords": [],
                              "live_started_at": null,
                              "numeric_id": "448640784",
                              "scheduled_start_at": null,
                              "secondary_category": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-24T11:01:00Z",
                          "text": null,
                          "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/25/s8/1/g/a/y/9/gay9A.OvCc-small-Bongino-Weekend-Report-Week..jpg",
                          "title": "Bongino Weekend Report - Week of 10/19/26",
                          "type": "video",
                          "unknown_fields": [
                            "hashtags",
                            "mentions",
                            "platform_specific.rumble.keywords"
                          ],
                          "url": "https://rumble.com/v7haadi-bongino-weekend-report-week-of-101926.html"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://hugh.cdn.rumble.cloud/video/z8/U/K/d/b/UKdba.baa.4-bongino-t8rqq7.jpeg",
                            "display_name": "The Dan Bongino Show",
                            "id": "_c276782",
                            "is_verified": true,
                            "url": "https://rumble.com/c/bongino",
                            "username": "bongino"
                          },
                          "coauthors": [],
                          "duration_ms": 3316000,
                          "hashtags": [],
                          "id": "v7gyjd4",
                          "is_nsfw": false,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 3316000,
                              "expires_at": null,
                              "height": 1080,
                              "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/bd/s8/1/i/k/s/7/iks7A.OvCc-small-Bongino-Weekend-Report-Week..jpg",
                              "type": "video",
                              "url": "https://hugh.cdn.rumble.cloud/video/fww1/bd/s8/2/i/k/s/7/iks7A.haa.mp4",
                              "width": 1920
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 119,
                            "like_count": 1170,
                            "quote_count": null,
                            "repost_count": 2,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 257009
                          },
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_follower_count": 3673478,
                              "caption_tracks": [],
                              "category": null,
                              "concurrent_viewer_count": null,
                              "dislike_count": 25,
                              "embed_id": "v7es6fm",
                              "embed_url": "https://rumble.com/embed/v7es6fm/",
                              "files": [],
                              "is_age_restricted": false,
                              "is_live_now": false,
                              "keywords": [],
                              "live_started_at": null,
                              "numeric_id": "448092562",
                              "scheduled_start_at": null,
                              "secondary_category": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-17T13:00:00Z",
                          "text": null,
                          "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/bd/s8/1/i/k/s/7/iks7A.OvCc-small-Bongino-Weekend-Report-Week..jpg",
                          "title": "Bongino Weekend Report - Week of 10/12/26",
                          "type": "video",
                          "unknown_fields": [
                            "hashtags",
                            "mentions",
                            "platform_specific.rumble.keywords"
                          ],
                          "url": "https://rumble.com/v7gyjd4-bongino-weekend-report-week-of-101226.html"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://hugh.cdn.rumble.cloud/video/z8/U/K/d/b/UKdba.baa.4-bongino-t8rqq7.jpeg",
                            "display_name": "The Dan Bongino Show",
                            "id": "_c276782",
                            "is_verified": true,
                            "url": "https://rumble.com/c/bongino",
                            "username": "bongino"
                          },
                          "coauthors": [],
                          "duration_ms": 3350000,
                          "hashtags": [],
                          "id": "v7go45s",
                          "is_nsfw": false,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 3350000,
                              "expires_at": null,
                              "height": 1080,
                              "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fwe2/2c/s8/1/q/C/B/5/qCB5A.OvCc-small-Bongino-Weekend-Report-Week..jpg",
                              "type": "video",
                              "url": "https://hugh.cdn.rumble.cloud/video/fwe2/2c/s8/2/q/C/B/5/qCB5A.haa.mp4",
                              "width": 1920
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 164,
                            "like_count": 1143,
                            "quote_count": null,
                            "repost_count": 0,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 265418
                          },
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_follower_count": 3673477,
                              "caption_tracks": [],
                              "category": null,
                              "concurrent_viewer_count": null,
                              "dislike_count": 22,
                              "embed_id": "v7ehr8a",
                              "embed_url": "https://rumble.com/embed/v7ehr8a/",
                              "files": [],
                              "is_age_restricted": false,
                              "is_live_now": false,
                              "keywords": [],
                              "live_started_at": null,
                              "numeric_id": "447606298",
                              "scheduled_start_at": null,
                              "secondary_category": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-10T16:03:02Z",
                          "text": null,
                          "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fwe2/2c/s8/1/q/C/B/5/qCB5A.OvCc-small-Bongino-Weekend-Report-Week..jpg",
                          "title": "Bongino Weekend Report - Week of 10/05/26",
                          "type": "video",
                          "unknown_fields": [
                            "hashtags",
                            "mentions",
                            "platform_specific.rumble.keywords"
                          ],
                          "url": "https://rumble.com/v7go45s-bongino-weekend-report-week-of-100526.html"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "rumble",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "_c276782",
                          "url": "https://rumble.com/c/bongino"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RumblePostsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "A Rumble channel's or user's videos, shorts and live streams",
        "tags": [
          "Rumble"
        ],
        "x-socialtap-endpoint": "rumble.posts",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 3600,
          "free_filtered_pages": true,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "Rumble's upload order (newest uploads first, not strictly by published_at)",
          "orders": {
            "newest": "Rumble's upload order (newest uploads first, not strictly by published_at)",
            "popular": "Rumble's View count order (most viewed first)"
          },
          "page_max": 25,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": ""
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/rumble/profile": {
      "get": {
        "description": "Returns a public Rumble channel or user: Rumble's own ID for it (the one Rumble's video data names the uploader by) and its name, display name, description, avatar, banner, verification badge, the social links it lists with their labels, its join date, follower count and exact video and lifetime view counts, and which kind of account it is with the ID of the user who owns it. Accepts a channel or user name, any channel or user link with any tab, or a channel's ID.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/rumble/profile/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/rumble/profile/"
        },
        "operationId": "rumble.profile.get",
        "parameters": [
          {
            "description": "Rumble channel or user: a bare name (Bongino: a channel, else the user of that name), c/<name> for a channel or user/<name> for a user, any channel or user link with any tab after it (rumble.com/c/Bongino, rumble.com/c/Bongino/videos, rumble.com/user/vivafrei/about, the root rumble.com/Bongino link), or a channel's id as this API returns it (_c276782) or its c/c-<channel id> name (c/c-276782, which every channel has). A user's _u… id is refused: Rumble's public pages cannot look a user up by ID, so send its name. Names are case-insensitive.",
            "example": "Bongino",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "Rumble channel or user: a bare name (Bongino: a channel, else the user of that name), c/<name> for a channel or user/<name> for a user, any channel or user link with any tab after it (rumble.com/c/Bongino, rumble.com/c/Bongino/videos, rumble.com/user/vivafrei/about, the root rumble.com/Bongino link), or a channel's id as this API returns it (_c276782) or its c/c-<channel id> name (c/c-276782, which every channel has). A user's _u… id is refused: Rumble's public pages cannot look a user up by ID, so send its name. Names are case-insensitive.",
              "examples": [
                "Bongino"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [
                          "metrics.follower_count",
                          "created_at"
                        ],
                        "avatar_url": "https://hugh.cdn.rumble.cloud/video/z8/U/K/d/b/UKdba.baa.4-bongino-t8rqq7.jpeg",
                        "banner_url": "https://hugh.cdn.rumble.cloud/video/z8/U/K/d/b/UKdba.caa-bongino-tbhrxo.png",
                        "bio": "The official channel for The Dan Bongino Show®. A former Deputy Director of the FBI, Secret Service Agent, NYPD officer, and best-selling author, Dan Bongino tackles the hot political issues, debunking both liberal and Republican establishment rhetoric.",
                        "category": null,
                        "country_code": null,
                        "created_at": "2020-09-16T00:00:00Z",
                        "display_name": "The Dan Bongino Show",
                        "external_links": [
                          {
                            "title": "Twitter",
                            "url": "https://twitter.com/dbongino"
                          },
                          {
                            "title": "Facebook",
                            "url": "https://facebook.com/danbongino"
                          },
                          {
                            "title": "Instagram",
                            "url": "https://instagram.com/dbongino"
                          }
                        ],
                        "id": "_c276782",
                        "is_private": false,
                        "is_verified": true,
                        "location": null,
                        "metrics": {
                          "follower_count": 3670000,
                          "following_count": null,
                          "post_count": 2136,
                          "total_like_count": null,
                          "total_view_count": 389354965
                        },
                        "platform": "rumble",
                        "platform_specific": {
                          "rumble": {
                            "account_type": "channel",
                            "numeric_id": "276782",
                            "user_id": "_u169h4"
                          }
                        },
                        "type": "unknown",
                        "unknown_fields": [],
                        "url": "https://rumble.com/c/bongino",
                        "username": "bongino"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "rumble",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "_c276782",
                          "url": "https://rumble.com/c/bongino"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RumbleProfileResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Public Rumble channel or user profile and its counts",
        "tags": [
          "Rumble"
        ],
        "x-socialtap-endpoint": "rumble.profile",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "profile",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/rumble/search_posts": {
      "get": {
        "description": "Searches Rumble's public videos and live streams, or its shorts, by keyword and returns them a page at a time: each video's link, title, thumbnail, exact upload time, real length, views, likes, dislikes and comments, its channel with the verification badge, and whether a stream is on air with its viewer count. Shorts also carry exact counts, the channel's follower count and the video file. Sort by relevance, newest or most viewed, and filter by upload date and length with Rumble's own filters.\n\nReturns `{data, page, meta}`: `data` holds up to 36 `Post` items (the shared schema, the same on every platform), Rumble's relevance order with sort=relevance (the default), newest first with sort=newest, Rumble's View count order (most viewed first) with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit (page) per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/"
        },
        "operationId": "rumble.search_posts.list",
        "parameters": [
          {
            "description": "Keywords, matched by Rumble's search against titles and channels.",
            "example": "cats",
            "in": "query",
            "name": "query",
            "required": true,
            "schema": {
              "description": "Keywords, matched by Rumble's search against titles and channels.",
              "examples": [
                "cats"
              ],
              "maxLength": 512,
              "type": "string"
            }
          },
          {
            "description": "The search tab to list: videos (default; videos and live streams) or shorts.",
            "example": "shorts",
            "in": "query",
            "name": "tab",
            "schema": {
              "description": "The search tab to list: videos (default; videos and live streams) or shorts.",
              "enum": [
                "videos",
                "shorts"
              ],
              "examples": [
                "shorts"
              ],
              "type": "string"
            }
          },
          {
            "description": "Order of the results. relevance (default): Rumble's best match. newest: newest uploads first. popular: Rumble's View count order (most viewed first).",
            "example": "",
            "in": "query",
            "name": "sort",
            "schema": {
              "default": "relevance",
              "description": "Order of the results. relevance (default): Rumble's best match. newest: newest uploads first. popular: Rumble's View count order (most viewed first).",
              "enum": [
                "relevance",
                "newest",
                "popular"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Rumble's upload-date filter is applied when it covers since (the last day, week, month or year), so fewer pages are fetched.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Rumble's upload-date filter is applied when it covers since (the last day, week, month or year), so fewer pages are fetched.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only short videos (Rumble's Under 4 minutes) or long ones (Over 20 minutes). Any length when omitted.",
            "example": "long",
            "in": "query",
            "name": "duration",
            "schema": {
              "description": "Only short videos (Rumble's Under 4 minutes) or long ones (Over 20 minutes). Any length when omitted.",
              "enum": [
                "short",
                "long"
              ],
              "examples": [
                "long"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 36,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 36,
              "maximum": 36,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": null,
                            "display_name": "ViralHog",
                            "id": "_u7bbl",
                            "is_verified": false,
                            "url": "https://rumble.com/user/ViralHog",
                            "username": "user/ViralHog"
                          },
                          "coauthors": [],
                          "duration_ms": 28000,
                          "hashtags": [],
                          "id": "v7hfhey",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 28000,
                              "expires_at": null,
                              "height": null,
                              "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/39/s8/6/Q/l/t/-/Qlt-A.oq1b.jpg",
                              "type": "video",
                              "url": null,
                              "width": null
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": null,
                            "like_count": 3,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 254
                          },
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_follower_count": null,
                              "caption_tracks": [],
                              "category": null,
                              "concurrent_viewer_count": null,
                              "dislike_count": 0,
                              "embed_id": null,
                              "embed_url": null,
                              "files": [],
                              "is_age_restricted": null,
                              "is_live_now": false,
                              "keywords": [],
                              "live_started_at": null,
                              "numeric_id": null,
                              "scheduled_start_at": null,
                              "secondary_category": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-26T19:34:46Z",
                          "text": null,
                          "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/39/s8/6/Q/l/t/-/Qlt-A.oq1b.jpg",
                          "title": "Orange Cat Sits Like Human On Fuzzy Couch",
                          "type": "video",
                          "unknown_fields": [
                            "hashtags",
                            "mentions",
                            "platform_specific.rumble.keywords"
                          ],
                          "url": "https://rumble.com/v7hfhey-orange-cat-sits-like-human-on-fuzzy-couch.html"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": null,
                            "display_name": "SereneChristine",
                            "id": "_urv80h",
                            "is_verified": false,
                            "url": "https://rumble.com/user/SereneChristine",
                            "username": "user/SereneChristine"
                          },
                          "coauthors": [],
                          "duration_ms": 932000,
                          "hashtags": [],
                          "id": "v7hdue2",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 932000,
                              "expires_at": null,
                              "height": null,
                              "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fwe2/1e/s8/1/A/G/a/-/AGa-A.oq1b-small-The-Book-of-Enoch-Reveals-W..jpg",
                              "type": "video",
                              "url": null,
                              "width": null
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": null,
                            "like_count": 4,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 400
                          },
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_follower_count": null,
                              "caption_tracks": [],
                              "category": null,
                              "concurrent_viewer_count": null,
                              "dislike_count": 1,
                              "embed_id": null,
                              "embed_url": null,
                              "files": [],
                              "is_age_restricted": null,
                              "is_live_now": false,
                              "keywords": [],
                              "live_started_at": null,
                              "numeric_id": null,
                              "scheduled_start_at": null,
                              "secondary_category": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-25T20:04:50Z",
                          "text": null,
                          "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fwe2/1e/s8/1/A/G/a/-/AGa-A.oq1b-small-The-Book-of-Enoch-Reveals-W..jpg",
                          "title": "The Book of Enoch Reveals Why Cats Were Sent to Earth — And Why the Church Removed That Chapter",
                          "type": "video",
                          "unknown_fields": [
                            "hashtags",
                            "mentions",
                            "platform_specific.rumble.keywords"
                          ],
                          "url": "https://rumble.com/v7hdue2-the-book-of-enoch-reveals-why-cats-were-sent-to-earth-and-why-the-church-re.html"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": null,
                            "display_name": "tubewatch1",
                            "id": "_utpvcv",
                            "is_verified": false,
                            "url": "https://rumble.com/user/tubewatch1",
                            "username": "user/tubewatch1"
                          },
                          "coauthors": [],
                          "duration_ms": 100000,
                          "hashtags": [],
                          "id": "v7hhiau",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 100000,
                              "expires_at": null,
                              "height": null,
                              "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/03/s8/6/M/p/Q/-/MpQ-A.oq1b.jpg",
                              "type": "video",
                              "url": null,
                              "width": null
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 1,
                            "like_count": null,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 211
                          },
                          "platform": "rumble",
                          "platform_specific": {
                            "rumble": {
                              "author_follower_count": null,
                              "caption_tracks": [],
                              "category": null,
                              "concurrent_viewer_count": null,
                              "dislike_count": null,
                              "embed_id": null,
                              "embed_url": null,
                              "files": [],
                              "is_age_restricted": null,
                              "is_live_now": false,
                              "keywords": [],
                              "live_started_at": null,
                              "numeric_id": null,
                              "scheduled_start_at": null,
                              "secondary_category": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-27T22:19:31Z",
                          "text": null,
                          "thumbnail_url": "https://hugh.cdn.rumble.cloud/video/fww1/03/s8/6/M/p/Q/-/MpQ-A.oq1b.jpg",
                          "title": "Pretty Peaceful Precious Piper - My Adopted Shelter Cat Vlog",
                          "type": "video",
                          "unknown_fields": [
                            "hashtags",
                            "mentions",
                            "platform_specific.rumble.keywords"
                          ],
                          "url": "https://rumble.com/v7hhiau-pretty-peaceful-precious-piper-my-adopted-shelter-cat-vlog.html"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "rumble",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": null,
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RumbleSearch_postsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Search Rumble videos, live streams and shorts by keyword",
        "tags": [
          "Rumble"
        ],
        "x-socialtap-endpoint": "rumble.search_posts",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 3600,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "Rumble's relevance order",
          "orders": {
            "newest": "newest first",
            "popular": "Rumble's View count order (most viewed first)",
            "relevance": "Rumble's relevance order"
          },
          "page_max": 36,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/rumble/transcript": {
      "get": {
        "description": "Returns the timed transcript of a public Rumble video, short or past live stream: the uploader's caption track when there is one, otherwise Rumble's automatic captions, as segments with start and end times and the full text, in the language you ask for when Rumble has it. Each answer says which track it used, links its WebVTT file and lists every track the video has. Videos without captions are transcribed from their audio with speech-to-text. Accepts every Rumble video link form, embed links included, or a bare video ID.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/"
        },
        "operationId": "rumble.transcript.get",
        "parameters": [
          {
            "description": "Rumble video, short or live stream URL (rumble.com/v…-title.html, /shorts/v…, /share/v…, /embed/v…/) or a video ID (v…).",
            "example": "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "Rumble video, short or live stream URL (rumble.com/v…-title.html, /shorts/v…, /share/v…, /embed/v…/) or a video ID (v…).",
              "examples": [
                "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Selects the caption track: an uploaded track in that language before Rumble's automatic one. When the video has no track in that language, the default track is returned (language says which). Default: an uploaded track in the spoken language, else Rumble's automatic captions.",
            "example": "en",
            "in": "query",
            "name": "lang",
            "schema": {
              "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Selects the caption track: an uploaded track in that language before Rumble's automatic one. When the video has no track in that language, the default track is returned (language says which). Default: an uploaded track in the spoken language, else Rumble's automatic captions.",
              "examples": [
                "en"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "available_languages": [
                          "en"
                        ],
                        "duration_ms": 1678000,
                        "id": "v79xhhm",
                        "is_auto_generated": true,
                        "language": "en",
                        "platform": "rumble",
                        "platform_specific": {
                          "rumble": {
                            "caption_tracks": [
                              {
                                "is_auto_generated": true,
                                "label": "English (auto)",
                                "language": "en",
                                "url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/11/k/V/p/o/kVpoA.fn8Si.1.vtt"
                              }
                            ],
                            "caption_url": "https://hugh.cdn.rumble.cloud/video/fwe2/2f/s8/11/k/V/p/o/kVpoA.fn8Si.1.vtt",
                            "track_label": "English (auto)"
                          }
                        },
                        "segments": [
                          {
                            "end_ms": 11030,
                            "start_ms": 6830,
                            "text": "Let's get into these questions, and we'll try and get through as many as we can."
                          },
                          {
                            "end_ms": 15630,
                            "start_ms": 11030,
                            "text": "The first one is from Christi Marbet, who says there were a few questions about this."
                          },
                          {
                            "end_ms": 17730,
                            "start_ms": 15630,
                            "text": "They want you to comment on the following, quote,"
                          }
                        ],
                        "source": "captions",
                        "text": "Let's get into these questions, and we'll try and get through as many as we can. The first one is from Christi Marbet, who says there were a few questions about this. They want you to comment on the following, quote, the Christoph piece on Palestinian rape in Israel, and its supp…",
                        "url": "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "rumble",
                        "source": "captions",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "v79xhhm",
                          "url": "https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RumbleTranscriptResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "no_transcript": {
                    "$ref": "#/components/examples/no_transcript"
                  },
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.\n\n`no_transcript`: The media exists but has no transcript: no caption track and no speech to transcribe. Do not retry; try another language with lang if the platform offers one.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Rumble video transcript",
        "tags": [
          "Rumble"
        ],
        "x-socialtap-endpoint": "rumble.transcript",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 122,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "captions"
            },
            {
              "credits": 2,
              "label": "2 credits + 2 per started minute of media",
              "max": 122,
              "per": 2,
              "source": "asr",
              "unit": "media_minute",
              "unit_max": 60
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "transcript",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/security_events": {
      "get": {
        "description": "The signed-in person's sign-ins, failed sign-ins, password, email, two-factor and session changes, newest first, with the network and browser each came from. Kept `security_events_retention_s` (90 days). Free.\n\n**Auth:** the dashboard session cookie.",
        "operationId": "security_events.list",
        "parameters": [
          {
            "description": "Events per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page; omit to start from the newest.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "created_at": {
                            "description": "When it happened, RFC 3339 UTC.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "id": {
                            "description": "Event ID (sev_…).",
                            "type": "string"
                          },
                          "method": {
                            "description": "How, where it applies: password, google, github, totp or backup_code.",
                            "maxLength": 32,
                            "type": "string"
                          },
                          "network": {
                            "description": "The network it came from: the client's IPv4 address or IPv6 /64.",
                            "type": "string"
                          },
                          "object": {
                            "description": "Always security_event.",
                            "enum": [
                              "security_event"
                            ],
                            "type": "string"
                          },
                          "type": {
                            "description": "What happened.",
                            "enum": [
                              "sign_in",
                              "sign_in_failed",
                              "sign_up",
                              "email_verified",
                              "password_reset",
                              "password_changed",
                              "email_changed",
                              "provider_linked",
                              "provider_unlinked",
                              "two_factor_enabled",
                              "two_factor_disabled",
                              "two_factor_failed",
                              "session_revoked",
                              "sign_out",
                              "unproven_access_revoked",
                              "sign_up_declined"
                            ],
                            "type": "string"
                          },
                          "user_agent": {
                            "description": "The browser's user agent, at most 256 characters.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "type",
                          "network",
                          "user_agent",
                          "created_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List sign-in and security events",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "summary": "List sign-in and security events",
        "tags": [
          "Signup"
        ],
        "x-socialtap-auth": {
          "auth": "session",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/session": {
      "delete": {
        "description": "Ends the session and clears its cookie.\n\n**Auth:** the dashboard session cookie.",
        "operationId": "session.delete",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "account_id": {
                          "description": "The signed-in account.",
                          "type": "string"
                        },
                        "activated_key_ids": {
                          "description": "IDs of the agent's pending live keys this call activated (agent_token); [] otherwise.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "credits_granted": {
                          "description": "Free credits this call granted (once per account); 0 otherwise.",
                          "type": "integer"
                        },
                        "email": {
                          "description": "The signed-in person's verified email address.",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the session ends, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "fresh_until": {
                          "description": "Until when this session may create API keys and change keys without re-verifying (password or two-factor code), RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "new_api_keys": {
                          "description": "Keys this call created, with their secrets shown only here (a new account's live and test keys, the first time its dashboard starts); [] otherwise.",
                          "items": {
                            "properties": {
                              "created_at": {
                                "description": "When the key was created, RFC 3339 UTC.",
                                "format": "date-time",
                                "type": "string"
                              },
                              "expires_at": {
                                "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "id": {
                                "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                                "type": "string"
                              },
                              "ip_allowlist": {
                                "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "last_used_at": {
                                "description": "About when the key was last used (updated at most hourly); null when never.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                                "enum": [
                                  "live",
                                  "test"
                                ],
                                "type": "string"
                              },
                              "name": {
                                "description": "Your label for the key.",
                                "type": "string"
                              },
                              "object": {
                                "description": "Always api_key.",
                                "enum": [
                                  "api_key"
                                ],
                                "type": "string"
                              },
                              "prefix": {
                                "description": "The secret's first characters, to recognize it.",
                                "type": "string"
                              },
                              "revoked_at": {
                                "description": "When the key was revoked; null while it is not.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "scopes": {
                                "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                                "items": {
                                  "enum": [
                                    "endpoints",
                                    "jobs",
                                    "account:read",
                                    "admin"
                                  ],
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "secret": {
                                "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.",
                                "type": "string"
                              },
                              "spend_limit": {
                                "description": "The key's spend limit and what it used this interval; null when the key has none.",
                                "properties": {
                                  "amount": {
                                    "description": "Most credits the key may spend per interval.",
                                    "type": "integer"
                                  },
                                  "interval": {
                                    "description": "Calendar day or month, UTC.",
                                    "enum": [
                                      "day",
                                      "month"
                                    ],
                                    "type": "string"
                                  },
                                  "resets_at": {
                                    "description": "Start of the next interval, RFC 3339 UTC.",
                                    "format": "date-time",
                                    "type": "string"
                                  },
                                  "used": {
                                    "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                    "type": "integer"
                                  }
                                },
                                "required": [
                                  "amount",
                                  "interval",
                                  "used",
                                  "resets_at"
                                ],
                                "type": [
                                  "object",
                                  "null"
                                ]
                              },
                              "status": {
                                "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                                "enum": [
                                  "active",
                                  "pending",
                                  "expired",
                                  "revoked"
                                ],
                                "type": "string"
                              }
                            },
                            "required": [
                              "object",
                              "id",
                              "name",
                              "mode",
                              "status",
                              "prefix",
                              "scopes",
                              "spend_limit",
                              "expires_at",
                              "ip_allowlist",
                              "created_at",
                              "last_used_at",
                              "revoked_at",
                              "secret"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        },
                        "object": {
                          "description": "Always session.",
                          "enum": [
                            "session"
                          ],
                          "type": "string"
                        },
                        "two_factor_enabled": {
                          "description": "Whether the signed-in person has two-factor authentication on.",
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "object",
                        "account_id",
                        "email",
                        "expires_at",
                        "new_api_keys",
                        "activated_key_ids",
                        "credits_granted",
                        "two_factor_enabled",
                        "fresh_until"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Sign out",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "summary": "Sign out",
        "tags": [
          "Signup"
        ],
        "x-socialtap-auth": {
          "auth": "session",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "get": {
        "description": "The signed-in person and account of the session cookie.\n\n**Auth:** the dashboard session cookie.",
        "operationId": "session.get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "account_id": {
                          "description": "The signed-in account.",
                          "type": "string"
                        },
                        "activated_key_ids": {
                          "description": "IDs of the agent's pending live keys this call activated (agent_token); [] otherwise.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "credits_granted": {
                          "description": "Free credits this call granted (once per account); 0 otherwise.",
                          "type": "integer"
                        },
                        "email": {
                          "description": "The signed-in person's verified email address.",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the session ends, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "fresh_until": {
                          "description": "Until when this session may create API keys and change keys without re-verifying (password or two-factor code), RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "new_api_keys": {
                          "description": "Keys this call created, with their secrets shown only here (a new account's live and test keys, the first time its dashboard starts); [] otherwise.",
                          "items": {
                            "properties": {
                              "created_at": {
                                "description": "When the key was created, RFC 3339 UTC.",
                                "format": "date-time",
                                "type": "string"
                              },
                              "expires_at": {
                                "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "id": {
                                "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                                "type": "string"
                              },
                              "ip_allowlist": {
                                "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "last_used_at": {
                                "description": "About when the key was last used (updated at most hourly); null when never.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                                "enum": [
                                  "live",
                                  "test"
                                ],
                                "type": "string"
                              },
                              "name": {
                                "description": "Your label for the key.",
                                "type": "string"
                              },
                              "object": {
                                "description": "Always api_key.",
                                "enum": [
                                  "api_key"
                                ],
                                "type": "string"
                              },
                              "prefix": {
                                "description": "The secret's first characters, to recognize it.",
                                "type": "string"
                              },
                              "revoked_at": {
                                "description": "When the key was revoked; null while it is not.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "scopes": {
                                "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                                "items": {
                                  "enum": [
                                    "endpoints",
                                    "jobs",
                                    "account:read",
                                    "admin"
                                  ],
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "secret": {
                                "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.",
                                "type": "string"
                              },
                              "spend_limit": {
                                "description": "The key's spend limit and what it used this interval; null when the key has none.",
                                "properties": {
                                  "amount": {
                                    "description": "Most credits the key may spend per interval.",
                                    "type": "integer"
                                  },
                                  "interval": {
                                    "description": "Calendar day or month, UTC.",
                                    "enum": [
                                      "day",
                                      "month"
                                    ],
                                    "type": "string"
                                  },
                                  "resets_at": {
                                    "description": "Start of the next interval, RFC 3339 UTC.",
                                    "format": "date-time",
                                    "type": "string"
                                  },
                                  "used": {
                                    "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                    "type": "integer"
                                  }
                                },
                                "required": [
                                  "amount",
                                  "interval",
                                  "used",
                                  "resets_at"
                                ],
                                "type": [
                                  "object",
                                  "null"
                                ]
                              },
                              "status": {
                                "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                                "enum": [
                                  "active",
                                  "pending",
                                  "expired",
                                  "revoked"
                                ],
                                "type": "string"
                              }
                            },
                            "required": [
                              "object",
                              "id",
                              "name",
                              "mode",
                              "status",
                              "prefix",
                              "scopes",
                              "spend_limit",
                              "expires_at",
                              "ip_allowlist",
                              "created_at",
                              "last_used_at",
                              "revoked_at",
                              "secret"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        },
                        "object": {
                          "description": "Always session.",
                          "enum": [
                            "session"
                          ],
                          "type": "string"
                        },
                        "two_factor_enabled": {
                          "description": "Whether the signed-in person has two-factor authentication on.",
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "object",
                        "account_id",
                        "email",
                        "expires_at",
                        "new_api_keys",
                        "activated_key_ids",
                        "credits_granted",
                        "two_factor_enabled",
                        "fresh_until"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get the dashboard session",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "summary": "Get the dashboard session",
        "tags": [
          "Signup"
        ],
        "x-socialtap-auth": {
          "auth": "session",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "post": {
        "description": "The dashboard calls it once it is signed in (people sign in with Google, GitHub or an email address and password on the sign-in page). The first call of a new account returns its live and test keys (secrets shown only here); with agent_token, it approves that agent signup, activating the agent's pending live key and granting the free credits. An account an agent opened that its owner signs in to without approving the agent gets fresh keys, and the agent's are revoked. Free.\n\n**Auth:** the dashboard session cookie.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "session.create",
        "parameters": [
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "agent_token": {
                    "description": "An agent signup's confirmation token (after # on the agent confirmation page): approves that agent, activating its pending live key. Only the signed-in owner of the address the agent named can use it.",
                    "maxLength": 200,
                    "minLength": 16,
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "account_id": {
                          "description": "The signed-in account.",
                          "type": "string"
                        },
                        "activated_key_ids": {
                          "description": "IDs of the agent's pending live keys this call activated (agent_token); [] otherwise.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "credits_granted": {
                          "description": "Free credits this call granted (once per account); 0 otherwise.",
                          "type": "integer"
                        },
                        "email": {
                          "description": "The signed-in person's verified email address.",
                          "type": "string"
                        },
                        "expires_at": {
                          "description": "When the session ends, RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "fresh_until": {
                          "description": "Until when this session may create API keys and change keys without re-verifying (password or two-factor code), RFC 3339 UTC.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "new_api_keys": {
                          "description": "Keys this call created, with their secrets shown only here (a new account's live and test keys, the first time its dashboard starts); [] otherwise.",
                          "items": {
                            "properties": {
                              "created_at": {
                                "description": "When the key was created, RFC 3339 UTC.",
                                "format": "date-time",
                                "type": "string"
                              },
                              "expires_at": {
                                "description": "When the key stops working, RFC 3339 UTC; null when it never expires.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "id": {
                                "description": "Key ID (key_…): manage the key with it. It is not the secret.",
                                "type": "string"
                              },
                              "ip_allowlist": {
                                "description": "IP addresses or CIDR ranges (IPv4 or IPv6) the key works from; [] = any.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "last_used_at": {
                                "description": "About when the key was last used (updated at most hourly); null when never.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "mode": {
                                "description": "live keys spend credits on real requests; test keys answer from recorded responses, free.",
                                "enum": [
                                  "live",
                                  "test"
                                ],
                                "type": "string"
                              },
                              "name": {
                                "description": "Your label for the key.",
                                "type": "string"
                              },
                              "object": {
                                "description": "Always api_key.",
                                "enum": [
                                  "api_key"
                                ],
                                "type": "string"
                              },
                              "prefix": {
                                "description": "The secret's first characters, to recognize it.",
                                "type": "string"
                              },
                              "revoked_at": {
                                "description": "When the key was revoked; null while it is not.",
                                "format": "date-time",
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "scopes": {
                                "description": "What the key may call: endpoints (data endpoints), jobs, account:read (account, usage, ledger, keys), admin (account settings and key management; includes account:read).",
                                "items": {
                                  "enum": [
                                    "endpoints",
                                    "jobs",
                                    "account:read",
                                    "admin"
                                  ],
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "secret": {
                                "description": "The key itself: send it in the x-api-key header. Shown only once: store it now.",
                                "type": "string"
                              },
                              "spend_limit": {
                                "description": "The key's spend limit and what it used this interval; null when the key has none.",
                                "properties": {
                                  "amount": {
                                    "description": "Most credits the key may spend per interval.",
                                    "type": "integer"
                                  },
                                  "interval": {
                                    "description": "Calendar day or month, UTC.",
                                    "enum": [
                                      "day",
                                      "month"
                                    ],
                                    "type": "string"
                                  },
                                  "resets_at": {
                                    "description": "Start of the next interval, RFC 3339 UTC.",
                                    "format": "date-time",
                                    "type": "string"
                                  },
                                  "used": {
                                    "description": "Credits the key spent this interval, plus what its requests in flight hold.",
                                    "type": "integer"
                                  }
                                },
                                "required": [
                                  "amount",
                                  "interval",
                                  "used",
                                  "resets_at"
                                ],
                                "type": [
                                  "object",
                                  "null"
                                ]
                              },
                              "status": {
                                "description": "pending: created by an agent signup and waiting for the owner's email confirmation (it can only read GET /v1/account). expired: past expires_at.",
                                "enum": [
                                  "active",
                                  "pending",
                                  "expired",
                                  "revoked"
                                ],
                                "type": "string"
                              }
                            },
                            "required": [
                              "object",
                              "id",
                              "name",
                              "mode",
                              "status",
                              "prefix",
                              "scopes",
                              "spend_limit",
                              "expires_at",
                              "ip_allowlist",
                              "created_at",
                              "last_used_at",
                              "revoked_at",
                              "secret"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        },
                        "object": {
                          "description": "Always session.",
                          "enum": [
                            "session"
                          ],
                          "type": "string"
                        },
                        "two_factor_enabled": {
                          "description": "Whether the signed-in person has two-factor authentication on.",
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "object",
                        "account_id",
                        "email",
                        "expires_at",
                        "new_api_keys",
                        "activated_key_ids",
                        "credits_granted",
                        "two_factor_enabled",
                        "fresh_until"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Start the dashboard: set up the account",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "session": []
          }
        ],
        "summary": "Start the dashboard: set up the account",
        "tags": [
          "Signup"
        ],
        "x-socialtap-auth": {
          "auth": "session",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/threads/profile": {
      "get": {
        "description": "Returns a public Threads account: user ID, username, display name, bio, the links in its bio with their titles, the largest profile picture, verification badge, whether the account is private, and the exact follower count, plus the topic labels Threads shows on the profile and which bio links Threads marks verified. Accepts a username with or without the @, the account's numeric id, or any threads.com or threads.net profile link.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (api) · 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/threads/profile/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/threads/profile/"
        },
        "operationId": "threads.profile.get",
        "parameters": [
          {
            "description": "Threads username with or without the @ (zuck, @zuck), the account's numeric id, or a profile link (threads.com/@zuck, threads.net/@zuck, with or without a tab such as /replies, /reposts or /media, and with any query such as ?hl=es). Usernames are case-insensitive. A number of 5 or more digits is an account id; @ before it is a username.",
            "example": "https://www.threads.com/@zuck",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "Threads username with or without the @ (zuck, @zuck), the account's numeric id, or a profile link (threads.com/@zuck, threads.net/@zuck, with or without a tab such as /replies, /reposts or /media, and with any query such as ?hl=es). Usernames are case-insensitive. A number of 5 or more digits is an account id; @ before it is a username.",
              "examples": [
                "zuck"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [],
                        "avatar_url": "https://scontent-atl3-1.cdninstagram.com/v/t51.82787-19/825322135_17989325280103224_1252773933700107438_n.jpg?stp=dst-jpg_s640x640_tt6&_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&efg=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.cdninstagram.com&_nc_gid…",
                        "banner_url": null,
                        "bio": "Mostly superintelligence and MMA takes",
                        "category": null,
                        "country_code": null,
                        "created_at": null,
                        "display_name": "Mark Zuckerberg",
                        "external_links": [],
                        "id": "63055343223",
                        "is_private": false,
                        "is_verified": true,
                        "location": null,
                        "metrics": {
                          "follower_count": 5751366,
                          "following_count": null,
                          "post_count": null,
                          "total_like_count": null,
                          "total_view_count": null
                        },
                        "platform": "threads",
                        "platform_specific": {
                          "threads": {
                            "interest_tags": [
                              "AI Threads",
                              "UFC Threads",
                              "AI"
                            ],
                            "verified_link_urls": []
                          }
                        },
                        "type": "unknown",
                        "unknown_fields": [],
                        "url": "https://www.threads.com/@zuck",
                        "username": "zuck"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "threads",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "63055343223",
                          "url": "https://www.threads.com/@zuck"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ThreadsProfileResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Public Threads profile with exact follower counts",
        "tags": [
          "Threads"
        ],
        "x-socialtap-endpoint": "threads.profile",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "api"
            },
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "profile",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/tiktok/comments": {
      "get": {
        "description": "Returns the public top-level comments of a TikTok video or photo post, a page at a time, in TikTok's own ranking: text, exact posting time, exact like and reply counts, the commenter's username, name, ID and verified badge, the comment's language, and whether it is pinned, liked by the creator or written by the creator. Follow page.next_cursor for more. Accepts tiktok.com video and photo links, mobile, embed and player URLs, vm./vt./t/ share links, or a numeric video ID.\n\nReturns `{data, page, meta}`: `data` holds up to 50 `Comment` items (the shared schema, the same on every platform), TikTok's comment ranking (the order its app shows). For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit (api) per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/"
        },
        "operationId": "tiktok.comments.list",
        "parameters": [
          {
            "description": "TikTok video or photo post URL (tiktok.com/@user/video/<id>, /@user/photo/<id>, m.tiktok.com/v/<id>.html, embed and player URLs, vm.tiktok.com/<code>, vt.tiktok.com/<code>, tiktok.com/t/<code>) or a numeric video ID.",
            "example": "https://www.tiktok.com/@scout2015/video/6718335390845095173",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "TikTok video or photo post URL (tiktok.com/@user/video/<id>, /@user/photo/<id>, m.tiktok.com/v/<id>.html, embed and player URLs, vm.tiktok.com/<code>, vt.tiktok.com/<code>, tiktok.com/t/<code>) or a numeric video ID.",
              "examples": [
                "https://www.tiktok.com/@scout2015/video/6718335390845095173"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 50,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 50,
              "maximum": 50,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7336370956674203653~tplv-tiktokx-cropcenter:100:100.jpg?dr=9640&refresh_token=8c568077&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=30310797&shcp=ff37627b&idc=useast5",
                            "display_name": "flamigoo",
                            "id": "6650133637952618502",
                            "is_verified": false,
                            "url": "https://www.tiktok.com/@flamigo_kisses",
                            "username": "flamigo_kisses"
                          },
                          "edited_at": null,
                          "id": "6718335906996502534",
                          "is_by_post_author": false,
                          "is_edited": null,
                          "is_liked_by_author": false,
                          "is_pinned": false,
                          "metrics": {
                            "like_count": 166,
                            "reply_count": 49
                          },
                          "parent_id": null,
                          "platform": "tiktok",
                          "platform_specific": {
                            "tiktok": {
                              "language": null
                            }
                          },
                          "post_id": "6718335390845095173",
                          "published_at": "2019-07-27T13:34:35Z",
                          "text": "ok ;)\nodoreta\nhave fun~\n(it's a Serbian name)",
                          "unknown_fields": [],
                          "url": "https://m.tiktok.com/v/6718335390845095173.html?share_comment_id=6718335906996502534&share_item_id=6718335390845095173"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7331407432645509126~tplv-tiktokx-cropcenter:100:100.jpg?dr=9640&refresh_token=0687ce2b&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=30310797&shcp=ff37627b&idc=useast5",
                            "display_name": "vsco_room_xx",
                            "id": "6718326650415203333",
                            "is_verified": false,
                            "url": "https://www.tiktok.com/@vsco_room_xx",
                            "username": "vsco_room_xx"
                          },
                          "edited_at": null,
                          "id": "6722043930156417030",
                          "is_by_post_author": false,
                          "is_edited": null,
                          "is_liked_by_author": false,
                          "is_pinned": false,
                          "metrics": {
                            "like_count": 53,
                            "reply_count": 44
                          },
                          "parent_id": null,
                          "platform": "tiktok",
                          "platform_specific": {
                            "tiktok": {
                              "language": null
                            }
                          },
                          "post_id": "6718335390845095173",
                          "published_at": "2019-08-06T13:23:37Z",
                          "text": "srii good luck",
                          "unknown_fields": [],
                          "url": "https://m.tiktok.com/v/6718335390845095173.html?share_comment_id=6722043930156417030&share_item_id=6718335390845095173"
                        },
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7328085019259748357~tplv-tiktokx-cropcenter:100:100.jpg?dr=9640&refresh_token=50158ea6&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=30310797&shcp=ff37627b&idc=useast5",
                            "display_name": "Quit",
                            "id": "6627564337508761605",
                            "is_verified": false,
                            "url": "https://www.tiktok.com/@pretzelsticks0",
                            "username": "pretzelsticks0"
                          },
                          "edited_at": null,
                          "id": "6718336105873702917",
                          "is_by_post_author": false,
                          "is_edited": null,
                          "is_liked_by_author": true,
                          "is_pinned": false,
                          "metrics": {
                            "like_count": 345,
                            "reply_count": 20
                          },
                          "parent_id": null,
                          "platform": "tiktok",
                          "platform_specific": {
                            "tiktok": {
                              "language": null
                            }
                          },
                          "post_id": "6718335390845095173",
                          "published_at": "2019-07-27T13:35:22Z",
                          "text": "Well it’s pretty easy...and obvious 😂 hlysa",
                          "unknown_fields": [],
                          "url": "https://m.tiktok.com/v/6718335390845095173.html?share_comment_id=6718336105873702917&share_item_id=6718335390845095173"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "tiktok",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "6718335390845095173",
                          "url": "https://www.tiktok.com/@/video/6718335390845095173"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TiktokCommentsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Top-level comments of a TikTok video",
        "tags": [
          "TikTok"
        ],
        "x-socialtap-endpoint": "tiktok.comments",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 86400,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "TikTok's comment ranking (the order its app shows)",
          "page_max": 50,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "api"
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "comment",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/tiktok/post": {
      "get": {
        "description": "Returns a public TikTok video or photo post: caption, hashtags, tagged accounts, author, publish time, a cookie-free video link or every slideshow photo, cover, sound, tagged place, ad and AI labels, and view, like, comment, share and save counts, from a post or share link or a numeric ID.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/tiktok/post/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/tiktok/post/"
        },
        "operationId": "tiktok.post.get",
        "parameters": [
          {
            "description": "TikTok video or photo post link (web, mobile, embed or share link) or a numeric post ID.",
            "example": "https://www.tiktok.com/@scout2015/video/6718335390845095173",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "TikTok video or photo post link (web, mobile, embed or share link) or a numeric post ID.",
              "examples": [
                "https://www.tiktok.com/@niinoclock/video/7673108027645414678"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [
                          "duration_ms",
                          "media[].duration_ms",
                          "metrics.view_count"
                        ],
                        "author": {
                          "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/4cbe05e194623e3f19aef975d9fdf26c~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=1a7ec680&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                          "display_name": "Scout, Suki & Stella",
                          "id": "53279706535428096",
                          "is_verified": true,
                          "url": "https://www.tiktok.com/@scout2015",
                          "username": "scout2015"
                        },
                        "coauthors": [],
                        "duration_ms": 10000,
                        "hashtags": [
                          "foryoupage",
                          "petsoftiktok",
                          "aesthetic"
                        ],
                        "id": "6718335390845095173",
                        "is_nsfw": false,
                        "is_pinned": null,
                        "is_sponsored": null,
                        "language": "en",
                        "media": [
                          {
                            "alt_text": null,
                            "duration_ms": 10000,
                            "expires_at": "2026-10-25T18:00:00Z",
                            "height": 1024,
                            "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/2367c7d45cf54a1397abd0e72bf22eac~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                            "type": "video",
                            "url": "https://v19.tiktokcdn-us.com/SCRUBBED/f2a52380/video/tos/useast5/tos-useast5-ve-0068c002-tx/15fbafb086324317bf77a649580b1f95/?a=1233&bti=ODszNWYuMDE6&&bt=2389&ft=aEKfuqT0mIoPD12Qd0iI3wUM0_AbMeF~O5&mime_type=video_mp4&rc=ODw1Z2gzZ2Q1ODo4aGdnZUBpM245aWhvZ3U4bjMzZzczM0AzNWA1MWJiNWEx…",
                            "width": 576
                          }
                        ],
                        "mentions": [],
                        "metrics": {
                          "comment_count": 5716,
                          "like_count": 35200,
                          "quote_count": null,
                          "repost_count": null,
                          "save_count": 649,
                          "share_count": 1518,
                          "view_count": 159700
                        },
                        "platform": "tiktok",
                        "platform_specific": {
                          "tiktok": {
                            "author_sec_uid": "MS4wLjABAAAAPZWNdkF_cmVSPCvV0Y6MCsH29mlAOlMOX3ikzGvlfMm3K6OMZv-JrRImpEHxdIMI",
                            "country_code": "US",
                            "is_ad": false,
                            "is_ai_generated": false,
                            "location": null,
                            "music": {
                              "author_name": "tiff",
                              "cover_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/62c59c8c91226b51c36d2338519eb63e~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=ae9b518c&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                              "duration_ms": 10000,
                              "id": "6689804660171082501",
                              "is_original": true,
                              "play_url": "https://v19.tiktokcdn-us.com/SCRUBBED/f2a52380/video/tos/useast5/tos-useast5-v-27dcd7-tx/fdec9588d6684e7d97da29739b9d0abf/?a=1233&bti=ODszNWYuMDE6&&bt=125&ft=GSDrKInz7ThMDnRGXq8Zmo&mime_type=audio_mpeg&rc=am48ZmQ6ZnFxNzMzNzU8M0Bpam48ZmQ6ZnFxNzMzNzU8M0BpNWRhcjRfaGBgLS1kMTZzYSNpNWR…",
                              "title": "original sound"
                            }
                          }
                        },
                        "platform_type": "video",
                        "published_at": "2019-07-27T13:32:38Z",
                        "text": "Scramble up ur name & I’ll try to guess it😍❤️ #foryoupage #petsoftiktok #aesthetic",
                        "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-p-0068/2367c7d45cf54a1397abd0e72bf22eac~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                        "title": null,
                        "type": "video",
                        "unknown_fields": [
                          "coauthors"
                        ],
                        "url": "https://www.tiktok.com/@scout2015/video/6718335390845095173"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "tiktok",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "6718335390845095173",
                          "url": "https://www.tiktok.com/@scout2015/video/6718335390845095173"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TiktokPostResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "TikTok video or photo post with media and metrics",
        "tags": [
          "TikTok"
        ],
        "x-socialtap-endpoint": "tiktok.post",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/tiktok/posts": {
      "get": {
        "description": "Returns a TikTok account's public videos and photo posts, newest first, with caption, hashtags, mentions, publish time, duration, cover, photos and engagement counts.\n\nReturns `{data, page, meta}`: `data` holds up to 15 `Post` items (the shared schema, the same on every platform), newest first. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/"
        },
        "operationId": "tiktok.posts.list",
        "parameters": [
          {
            "description": "TikTok username with or without the @, a profile URL (tiktok.com/@nasa) or a numeric user ID.",
            "example": "@khaby.lame",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "TikTok username with or without the @, a profile URL (tiktok.com/@nasa) or a numeric user ID.",
              "examples": [
                "nasa"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 15,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 15,
              "maximum": 15,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [
                            "metrics.view_count",
                            "metrics.like_count",
                            "metrics.share_count"
                          ],
                          "author": {
                            "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                            "display_name": "Khabane lame",
                            "id": "127905465618821121",
                            "is_verified": true,
                            "url": "https://www.tiktok.com/@khaby.lame",
                            "username": "khaby.lame"
                          },
                          "coauthors": [],
                          "duration_ms": 9000,
                          "hashtags": [
                            "learnfromkhaby",
                            "comedy"
                          ],
                          "id": "7697307919943060767",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": "en",
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 9000,
                              "expires_at": null,
                              "height": 1280,
                              "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oQbHQmFfa5VY3NlkEGDAQT00RzqAqBOETlEafj~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                              "type": "video",
                              "url": null,
                              "width": 720
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 7503,
                            "like_count": 305900,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": 16282,
                            "share_count": 32600,
                            "view_count": 4600000
                          },
                          "platform": "tiktok",
                          "platform_specific": {
                            "tiktok": {
                              "author_sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
                              "country_code": null,
                              "is_ad": false,
                              "is_ai_generated": true,
                              "location": null,
                              "music": {
                                "author_name": "Khabane lame",
                                "cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                                "duration_ms": 9000,
                                "id": "7697308007327730462",
                                "is_original": true,
                                "play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast8/tos-useast8-v-27dcd7-tx2/oEEIAbfkyMVIeCnAjGGKYI9gqpqTImLAAfYo09/?a=1988&bti=ODszNWYuMDE6&&bt=125&ft=GcAInInz7Th~v-RGXq8Zmo&mime_type=audio_mpeg&rc=M2lybXI5cnE4ZTMzaTU8NEBpM2lybXI5cnE4ZTMzaTU8NEBxYG5tMmRrNjZhLS1kMTJzYSNxYG5t…",
                                "title": "original sound"
                              }
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-16T16:46:21Z",
                          "text": "I guess is time to retire #learnfromkhaby #comedy 🥊",
                          "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oQbHQmFfa5VY3NlkEGDAQT00RzqAqBOETlEafj~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                          "title": null,
                          "type": "video",
                          "unknown_fields": [],
                          "url": "https://www.tiktok.com/@khaby.lame/video/7697307919943060767"
                        },
                        {
                          "approximate_fields": [
                            "metrics.view_count",
                            "metrics.like_count",
                            "metrics.comment_count"
                          ],
                          "author": {
                            "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                            "display_name": "Khabane lame",
                            "id": "127905465618821121",
                            "is_verified": true,
                            "url": "https://www.tiktok.com/@khaby.lame",
                            "username": "khaby.lame"
                          },
                          "coauthors": [],
                          "duration_ms": 30000,
                          "hashtags": [
                            "learnfromkhaby",
                            "comedy"
                          ],
                          "id": "7694335322922044703",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": "en",
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 30000,
                              "expires_at": null,
                              "height": 1280,
                              "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/osAHzWAIipBAxVMie5CIDqxK0ArEREAAEKVSfn~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                              "type": "video",
                              "url": null,
                              "width": 720
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 12600,
                            "like_count": 690100,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": 40145,
                            "share_count": 20800,
                            "view_count": 6900000
                          },
                          "platform": "tiktok",
                          "platform_specific": {
                            "tiktok": {
                              "author_sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
                              "country_code": null,
                              "is_ad": false,
                              "is_ai_generated": true,
                              "location": null,
                              "music": {
                                "author_name": "Khabane lame",
                                "cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                                "duration_ms": 30000,
                                "id": "7694335437137087262",
                                "is_original": true,
                                "play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast8/tos-useast8-v-27dcd7-tx2/o4fHr3qIArT5AEXEiCLVExDGAeqCAIOVe4joPR/?a=1988&bti=ODszNWYuMDE6&&bt=125&ft=GcAInInz7Th~v-RGXq8Zmo&mime_type=audio_mpeg&rc=M3lzeG45cm92ZTMzaTU8NEBpM3lzeG45cm92ZTMzaTU8NEBzNGtiMmRjXjBhLS1kMTJzYSNzNGti…",
                                "title": "original sound"
                              }
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-08T16:31:16Z",
                          "text": "Was the ball out, or was it just my imagination? 🤨#learnfromkhaby #comedy",
                          "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/osAHzWAIipBAxVMie5CIDqxK0ArEREAAEKVSfn~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                          "title": null,
                          "type": "video",
                          "unknown_fields": [],
                          "url": "https://www.tiktok.com/@khaby.lame/video/7694335322922044703"
                        },
                        {
                          "approximate_fields": [
                            "metrics.view_count",
                            "metrics.like_count",
                            "metrics.share_count"
                          ],
                          "author": {
                            "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                            "display_name": "Khabane lame",
                            "id": "127905465618821121",
                            "is_verified": true,
                            "url": "https://www.tiktok.com/@khaby.lame",
                            "username": "khaby.lame"
                          },
                          "coauthors": [],
                          "duration_ms": 34000,
                          "hashtags": [
                            "learnfromkhaby",
                            "comedy"
                          ],
                          "id": "7691740195418377502",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": "en",
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 34000,
                              "expires_at": null,
                              "height": 1280,
                              "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o0jRDQRMAbfFAlZX8eqGQcARBqerRfAHR7gVSU~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                              "type": "video",
                              "url": null,
                              "width": 720
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": 7325,
                            "like_count": 418500,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": 20087,
                            "share_count": 23900,
                            "view_count": 5000000
                          },
                          "platform": "tiktok",
                          "platform_specific": {
                            "tiktok": {
                              "author_sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
                              "country_code": null,
                              "is_ad": false,
                              "is_ai_generated": true,
                              "location": null,
                              "music": {
                                "author_name": "Khabane lame",
                                "cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=07918010&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                                "duration_ms": 34000,
                                "id": "7691740326570019615",
                                "is_original": true,
                                "play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/useast8/tos-useast8-v-27dcd7-tx2/ogcDFBGWoU0A8F0eIAAREf8XVjvDqICFsEDJAo/?a=1988&bti=ODszNWYuMDE6&&bt=125&ft=GcAInInz7Th~v-RGXq8Zmo&mime_type=audio_mpeg&rc=M3hmanQ5cjg7ZDMzaTU8NEBpM3hmanQ5cjg7ZDMzaTU8NEBjMGgyMmRzbnNhLS1kMTJzYSNjMGgy…",
                                "title": "original sound"
                              }
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2026-10-01T16:40:54Z",
                          "text": "Just give me 5 more minutes 😭#learnfromkhaby #comedy",
                          "thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o0jRDQRMAbfFAlZX8eqGQcARBqerRfAHR7gVSU~tplv-tiktokx-origin.image?dr=9636&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast5",
                          "title": null,
                          "type": "video",
                          "unknown_fields": [],
                          "url": "https://www.tiktok.com/@khaby.lame/video/7691740195418377502"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "tiktok",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "127905465618821121",
                          "url": "https://www.tiktok.com/@khaby.lame"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TiktokPostsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "A public TikTok account's videos and photo posts",
        "tags": [
          "TikTok"
        ],
        "x-socialtap-endpoint": "tiktok.posts",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 86400,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "newest first",
          "page_max": 15,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": ""
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/tiktok/profile": {
      "get": {
        "description": "Returns a public TikTok account: user ID, username, display name, bio, bio link, avatar, verification badge, whether the account is private, its business category, join date and exact follower, following, video and total like counts. Accepts a username with or without the @, a tiktok.com profile URL, or a numeric user ID.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/"
        },
        "operationId": "tiktok.profile.get",
        "parameters": [
          {
            "description": "TikTok username with or without the @ (nasa, @nasa), a profile URL (tiktok.com/@nasa, m.tiktok.com/@nasa, with or without query parameters), or a numeric user ID (tiktok.com/share/user/<id> or the bare ID). Usernames are case-insensitive.",
            "example": "https://www.tiktok.com/@nasa",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "TikTok username with or without the @ (nasa, @nasa), a profile URL (tiktok.com/@nasa, m.tiktok.com/@nasa, with or without query parameters), or a numeric user ID (tiktok.com/share/user/<id> or the bare ID). Usernames are case-insensitive.",
              "examples": [
                "nasa"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [],
                        "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=9341391e&x-expires=4070908800&x-signature=SCRUBBED&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast5",
                        "banner_url": null,
                        "bio": "Making the seemingly impossible, possible.✨",
                        "category": null,
                        "country_code": null,
                        "created_at": "2026-07-20T15:55:49Z",
                        "display_name": "NASA",
                        "external_links": [
                          {
                            "title": null,
                            "url": "https://science.nasa.gov/feature/artemis-ii-preliminary-lunar-science-report"
                          }
                        ],
                        "id": "7664638705177150477",
                        "is_private": false,
                        "is_verified": true,
                        "location": null,
                        "metrics": {
                          "follower_count": 2140425,
                          "following_count": 23,
                          "post_count": 60,
                          "total_like_count": 11385816,
                          "total_view_count": null
                        },
                        "platform": "tiktok",
                        "platform_specific": {},
                        "type": "organization",
                        "unknown_fields": [],
                        "url": "https://www.tiktok.com/@nasa",
                        "username": "nasa"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "tiktok",
                        "source": "page",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "7664638705177150477",
                          "url": "https://www.tiktok.com/@nasa"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TiktokProfileResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Public TikTok profile and follower counts",
        "tags": [
          "TikTok"
        ],
        "x-socialtap-endpoint": "tiktok.profile",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "profile",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/tiktok/transcript": {
      "get": {
        "description": "Returns the timed transcript of a public TikTok video: creator-edited captions, TikTok's auto-captions, or TikTok's own translation when you ask for another language with lang. Videos without any caption track are transcribed from their audio with speech-to-text. Accepts tiktok.com video, mobile, embed and vm./vt./t/ share links, or a numeric video ID.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/"
        },
        "operationId": "tiktok.transcript.get",
        "parameters": [
          {
            "description": "TikTok video URL (tiktok.com/@user/video/<id>, m.tiktok.com/v/<id>.html, vm.tiktok.com/<code>, vt.tiktok.com/<code>, tiktok.com/t/<code>, embed URLs) or a numeric video ID.",
            "example": "7673108027645414678",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "TikTok video URL (tiktok.com/@user/video/<id>, m.tiktok.com/v/<id>.html, vm.tiktok.com/<code>, vt.tiktok.com/<code>, tiktok.com/t/<code>, embed URLs) or a numeric video ID.",
              "examples": [
                "https://www.tiktok.com/@scout2015/video/6718335390845095173"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Selects the caption track (TikTok also offers its own translations); falls back to the video's original language, then any track. TikTok's three-letter codes (eng-US) work too.",
            "example": "en",
            "in": "query",
            "name": "lang",
            "schema": {
              "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Selects the caption track (TikTok also offers its own translations); falls back to the video's original language, then any track. TikTok's three-letter codes (eng-US) work too.",
              "examples": [
                "en"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "available_languages": [
                          "en"
                        ],
                        "duration_ms": 495000,
                        "id": "7673108027645414678",
                        "is_auto_generated": false,
                        "language": "en",
                        "platform": "tiktok",
                        "platform_specific": {},
                        "segments": [
                          {
                            "end_ms": 4820,
                            "start_ms": 100,
                            "text": "Let me show you how to make a Japanese cream stew!"
                          },
                          {
                            "end_ms": 8380,
                            "start_ms": 4821,
                            "text": "I think there is a way to definitely make it from scratch,"
                          },
                          {
                            "end_ms": 13120,
                            "start_ms": 8381,
                            "text": "but most Japanese people buy the stock for the cream stew."
                          }
                        ],
                        "source": "captions",
                        "text": "Let me show you how to make a Japanese cream stew! I think there is a way to definitely make it from scratch, but most Japanese people buy the stock for the cream stew. If you go to a Japanese supermarket, you can find this next to or near where the curry stock cubes are. This is…",
                        "url": "https://www.tiktok.com/@niinoclock/video/7673108027645414678"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "tiktok",
                        "source": "captions",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 668,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "7673108027645414678",
                          "url": "https://www.tiktok.com/@niinoclock/video/7673108027645414678"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TiktokTranscriptResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "no_transcript": {
                    "$ref": "#/components/examples/no_transcript"
                  },
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.\n\n`no_transcript`: The media exists but has no transcript: no caption track and no speech to transcribe. Do not retry; try another language with lang if the platform offers one.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "TikTok video transcript",
        "tags": [
          "TikTok"
        ],
        "x-socialtap-endpoint": "tiktok.transcript",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 122,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "captions"
            },
            {
              "credits": 2,
              "label": "2 credits + 2 per started minute of media",
              "max": 122,
              "per": 2,
              "source": "asr",
              "unit": "media_minute",
              "unit_max": 60
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "transcript",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/usage": {
      "get": {
        "description": "Requests, successes, failures, cache hits and credits charged per time bucket, optionally grouped by endpoint, key and outcome. Buckets are listed oldest first, cursor-paged. Data is complete to within about 5 minutes; credits reconcile with the ledger. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key gets an empty report: test requests are not metered.",
        "operationId": "usage.list",
        "parameters": [
          {
            "description": "Start, inclusive: RFC 3339 or a date (UTC), rounded down to the bucket. Default: 7 buckets before until.",
            "in": "query",
            "name": "since",
            "schema": {
              "maxLength": 40,
              "type": "string"
            }
          },
          {
            "description": "End, exclusive: RFC 3339 or a date (UTC). Default: now.",
            "in": "query",
            "name": "until",
            "schema": {
              "maxLength": 40,
              "type": "string"
            }
          },
          {
            "description": "Bucket size. Default 1d. At most 168 hourly or 31 daily buckets per page.",
            "in": "query",
            "name": "bucket_width",
            "schema": {
              "enum": [
                "1h",
                "1d"
              ],
              "type": "string"
            }
          },
          {
            "description": "Comma-separated subset of endpoint, api_key_id, status: each bucket has one result per combination. Default: one result per bucket.",
            "in": "query",
            "name": "group_by",
            "schema": {
              "maxLength": 64,
              "type": "string"
            }
          },
          {
            "description": "Only this endpoint ID (youtube.transcript).",
            "in": "query",
            "name": "endpoint",
            "schema": {
              "maxLength": 100,
              "type": "string"
            }
          },
          {
            "description": "Only this key's requests.",
            "in": "query",
            "name": "api_key_id",
            "schema": {
              "maxLength": 64,
              "type": "string"
            }
          },
          {
            "description": "Buckets per page (default and maximum: 31 daily or 168 hourly).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 168,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "ending_at": {
                            "description": "Bucket end, exclusive.",
                            "format": "date-time",
                            "type": "string"
                          },
                          "results": {
                            "description": "One entry per group (group_by); [] when the bucket had no requests.",
                            "items": {
                              "properties": {
                                "api_key_id": {
                                  "description": "Key ID; null unless grouped by api_key_id.",
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "cache_hits": {
                                  "description": "Successes served from the cache (free).",
                                  "type": "integer"
                                },
                                "credits_charged": {
                                  "description": "Credits charged.",
                                  "type": "integer"
                                },
                                "endpoint": {
                                  "description": "Endpoint ID; null unless grouped by endpoint.",
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "failed": {
                                  "description": "Requests answered with an error (free).",
                                  "type": "integer"
                                },
                                "requests": {
                                  "description": "Requests that reached an endpoint.",
                                  "type": "integer"
                                },
                                "status": {
                                  "description": "ok, or the error code the requests ended with; null unless grouped by status.",
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                },
                                "succeeded": {
                                  "description": "Requests answered with data.",
                                  "type": "integer"
                                }
                              },
                              "required": [
                                "endpoint",
                                "api_key_id",
                                "status",
                                "requests",
                                "succeeded",
                                "failed",
                                "cache_hits",
                                "credits_charged"
                              ],
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "starting_at": {
                            "description": "Bucket start, inclusive (RFC 3339 UTC).",
                            "format": "date-time",
                            "type": "string"
                          }
                        },
                        "required": [
                          "starting_at",
                          "ending_at",
                          "results"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Usage report: requests and credits over time",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Usage report: requests and credits over time",
        "tags": [
          "Account"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/webhook_endpoints": {
      "get": {
        "description": "The account's webhook endpoints, newest first; never their secrets. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.",
        "operationId": "webhook_endpoints.list",
        "parameters": [
          {
            "description": "Endpoints per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page; omit to start from the newest.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "created_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "description": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "disabled_reason": {
                            "description": "Why it is disabled: gone (it answered 410), failing (deliveries failed for 5 days), user. Null while enabled.",
                            "enum": [
                              "gone",
                              "failing",
                              "user"
                            ],
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "events": {
                            "description": "Event types it receives: types, prefix wildcards (job.*) or * for all.",
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "id": {
                            "description": "we_…",
                            "type": "string"
                          },
                          "object": {
                            "description": "Always webhook_endpoint.",
                            "enum": [
                              "webhook_endpoint"
                            ],
                            "type": "string"
                          },
                          "previous_secret_expires_at": {
                            "description": "Until then the previous secret signs too; null when none.",
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "secret": {
                            "description": "The signing secret (whsec_…): only in the create and rotate_secret answers. Store it.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "enum": [
                              "enabled",
                              "disabled"
                            ],
                            "type": "string"
                          },
                          "updated_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "url": {
                            "description": "https URL deliveries are POSTed to.",
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "url",
                          "events",
                          "description",
                          "status",
                          "disabled_reason",
                          "previous_secret_expires_at",
                          "created_at",
                          "updated_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List webhook endpoints",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List webhook endpoints",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "post": {
        "description": "Registers an https URL to receive the events it subscribes to, signed per Standard Webhooks. The answer is the only time `secret` is shown: store it to verify signatures. At most `max_endpoints` (16) per account and mode. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "webhook_endpoints.create",
        "parameters": [
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "description": {
                    "maxLength": 500,
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "events": {
                    "description": "Event types, prefix wildcards (job.*) or *.",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 32,
                    "minItems": 1,
                    "type": "array"
                  },
                  "url": {
                    "description": "An https URL on a public host (no IP addresses of private, loopback or link-local networks; redirects are not followed).",
                    "maxLength": 2048,
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "url",
                  "events"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "disabled_reason": {
                          "description": "Why it is disabled: gone (it answered 410), failing (deliveries failed for 5 days), user. Null while enabled.",
                          "enum": [
                            "gone",
                            "failing",
                            "user"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "events": {
                          "description": "Event types it receives: types, prefix wildcards (job.*) or * for all.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "id": {
                          "description": "we_…",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always webhook_endpoint.",
                          "enum": [
                            "webhook_endpoint"
                          ],
                          "type": "string"
                        },
                        "previous_secret_expires_at": {
                          "description": "Until then the previous secret signs too; null when none.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secret": {
                          "description": "The signing secret (whsec_…): only in the create and rotate_secret answers. Store it.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "enum": [
                            "enabled",
                            "disabled"
                          ],
                          "type": "string"
                        },
                        "updated_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "url": {
                          "description": "https URL deliveries are POSTed to.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "url",
                        "events",
                        "description",
                        "status",
                        "disabled_reason",
                        "previous_secret_expires_at",
                        "created_at",
                        "updated_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Register a webhook endpoint",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Register a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/webhook_endpoints/{id}": {
      "delete": {
        "description": "Deletes the endpoint; pending deliveries to it stop. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.",
        "operationId": "webhook_endpoints.delete",
        "parameters": [
          {
            "description": "Webhook endpoint ID (we_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "deleted": {
                          "description": "Always true.",
                          "type": "boolean"
                        },
                        "id": {
                          "type": "string"
                        },
                        "object": {
                          "description": "The deleted object's type (webhook_endpoint).",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "deleted"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Delete a webhook endpoint",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Delete a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "get": {
        "description": "One webhook endpoint (never its secret). Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.",
        "operationId": "webhook_endpoints.get",
        "parameters": [
          {
            "description": "Webhook endpoint ID (we_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "disabled_reason": {
                          "description": "Why it is disabled: gone (it answered 410), failing (deliveries failed for 5 days), user. Null while enabled.",
                          "enum": [
                            "gone",
                            "failing",
                            "user"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "events": {
                          "description": "Event types it receives: types, prefix wildcards (job.*) or * for all.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "id": {
                          "description": "we_…",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always webhook_endpoint.",
                          "enum": [
                            "webhook_endpoint"
                          ],
                          "type": "string"
                        },
                        "previous_secret_expires_at": {
                          "description": "Until then the previous secret signs too; null when none.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secret": {
                          "description": "The signing secret (whsec_…): only in the create and rotate_secret answers. Store it.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "enum": [
                            "enabled",
                            "disabled"
                          ],
                          "type": "string"
                        },
                        "updated_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "url": {
                          "description": "https URL deliveries are POSTed to.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "url",
                        "events",
                        "description",
                        "status",
                        "disabled_reason",
                        "previous_secret_expires_at",
                        "created_at",
                        "updated_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Get a webhook endpoint",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Get a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      },
      "patch": {
        "description": "Changes the URL, events, description or status; absent fields keep their value. Setting `status` to `enabled` re-enables an endpoint SocialTap disabled (see `disabled_reason`). Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.",
        "operationId": "webhook_endpoints.update",
        "parameters": [
          {
            "description": "Webhook endpoint ID (we_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "description": {
                    "maxLength": 500,
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "events": {
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  },
                  "status": {
                    "enum": [
                      "enabled",
                      "disabled"
                    ],
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "url": {
                    "maxLength": 2048,
                    "minLength": 1,
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "disabled_reason": {
                          "description": "Why it is disabled: gone (it answered 410), failing (deliveries failed for 5 days), user. Null while enabled.",
                          "enum": [
                            "gone",
                            "failing",
                            "user"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "events": {
                          "description": "Event types it receives: types, prefix wildcards (job.*) or * for all.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "id": {
                          "description": "we_…",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always webhook_endpoint.",
                          "enum": [
                            "webhook_endpoint"
                          ],
                          "type": "string"
                        },
                        "previous_secret_expires_at": {
                          "description": "Until then the previous secret signs too; null when none.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secret": {
                          "description": "The signing secret (whsec_…): only in the create and rotate_secret answers. Store it.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "enum": [
                            "enabled",
                            "disabled"
                          ],
                          "type": "string"
                        },
                        "updated_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "url": {
                          "description": "https URL deliveries are POSTed to.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "url",
                        "events",
                        "description",
                        "status",
                        "disabled_reason",
                        "previous_secret_expires_at",
                        "created_at",
                        "updated_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Update a webhook endpoint",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Update a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": false,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/webhook_endpoints/{id}/deliveries": {
      "get": {
        "description": "Every delivery of an event to this endpoint, newest first: its last attempt's status code, duration and the start of the response body, and when the next attempt is due. Free.\n\n**Auth:** an API key with the `account:read` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.",
        "operationId": "webhook_endpoints.deliveries.list",
        "parameters": [
          {
            "description": "Webhook endpoint ID (we_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only deliveries in this status.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "succeeded",
                "failed"
              ],
              "type": "string"
            }
          },
          {
            "description": "Deliveries per page (default and maximum 100).",
            "in": "query",
            "name": "limit",
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor of the previous page; omit to start from the newest.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 200,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "description": "This page's items.",
                      "items": {
                        "properties": {
                          "attempts": {
                            "description": "Attempts made so far.",
                            "type": "integer"
                          },
                          "created_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "delivered_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "duration_ms": {
                            "description": "The last attempt's duration.",
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "error": {
                            "description": "Why the last attempt failed when there was no response.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "event_type": {
                            "type": "string"
                          },
                          "id": {
                            "description": "whd_…",
                            "type": "string"
                          },
                          "next_attempt_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "object": {
                            "description": "Always webhook_delivery.",
                            "enum": [
                              "webhook_delivery"
                            ],
                            "type": "string"
                          },
                          "response_excerpt": {
                            "description": "The start of the last response body.",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "description": "pending: an attempt is due (next_attempt_at). failed: every attempt failed, or the endpoint was disabled or deleted.",
                            "enum": [
                              "pending",
                              "succeeded",
                              "failed"
                            ],
                            "type": "string"
                          },
                          "status_code": {
                            "description": "The last attempt's HTTP status; null when it got none (timeout, refused, blocked URL).",
                            "type": [
                              "integer",
                              "null"
                            ]
                          },
                          "webhook_endpoint_id": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "object",
                          "id",
                          "event_id",
                          "event_type",
                          "webhook_endpoint_id",
                          "status",
                          "attempts",
                          "status_code",
                          "duration_ms",
                          "response_excerpt",
                          "error",
                          "created_at",
                          "delivered_at",
                          "next_attempt_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    },
                    "page": {
                      "properties": {
                        "end_reason": {
                          "description": "Why there are no more pages; null while has_more is true. end: the list ended, or reached since/until. platform_limit: the platform stops serving further pages although the list goes on. max_pages: SocialTap's cap on pages in one walk. New values may be added. A short or empty page is not the end: only has_more false is.",
                          "enum": [
                            "end",
                            "platform_limit",
                            "max_pages"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "has_more": {
                          "description": "True when another page exists; then next_cursor is set. An empty page with has_more true is not the end.",
                          "type": "boolean"
                        },
                        "next_cursor": {
                          "description": "Pass as cursor, with the same other parameters, to get the next page; null at the end.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "next_cursor_expires_at": {
                          "description": "When next_cursor stops working, RFC 3339 UTC; null at the end. Don't store cursors.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "has_more",
                        "next_cursor",
                        "next_cursor_expires_at",
                        "end_reason"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "page",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "List an endpoint's delivery attempts",
            "headers": {
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "List an endpoint's delivery attempts",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "account:read"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited"
          ]
        }
      }
    },
    "/v1/webhook_endpoints/{id}/rotate_secret": {
      "post": {
        "description": "Issues a new secret, shown once in the answer. The previous one keeps signing too (a second `v1,` signature) for `previous_secret_expires_in` seconds, so receivers can switch without dropping a delivery. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "webhook_endpoints.rotate_secret",
        "parameters": [
          {
            "description": "Webhook endpoint ID (we_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "previous_secret_expires_in": {
                    "description": "Seconds the previous secret keeps signing (0 = stop now). Default: the maximum.",
                    "maximum": 86400,
                    "minimum": 0,
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "created_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "disabled_reason": {
                          "description": "Why it is disabled: gone (it answered 410), failing (deliveries failed for 5 days), user. Null while enabled.",
                          "enum": [
                            "gone",
                            "failing",
                            "user"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "events": {
                          "description": "Event types it receives: types, prefix wildcards (job.*) or * for all.",
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "id": {
                          "description": "we_…",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always webhook_endpoint.",
                          "enum": [
                            "webhook_endpoint"
                          ],
                          "type": "string"
                        },
                        "previous_secret_expires_at": {
                          "description": "Until then the previous secret signs too; null when none.",
                          "format": "date-time",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "secret": {
                          "description": "The signing secret (whsec_…): only in the create and rotate_secret answers. Store it.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "enum": [
                            "enabled",
                            "disabled"
                          ],
                          "type": "string"
                        },
                        "updated_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "url": {
                          "description": "https URL deliveries are POSTed to.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "url",
                        "events",
                        "description",
                        "status",
                        "disabled_reason",
                        "previous_secret_expires_at",
                        "created_at",
                        "updated_at"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Rotate a webhook endpoint's signing secret",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Rotate a webhook endpoint's signing secret",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/webhook_endpoints/{id}/test": {
      "post": {
        "description": "Emits a `webhook.test` event delivered to this endpoint only (signed and retried like any event). The answer is the event; its delivery appears in the endpoint's deliveries. Free.\n\n**Auth:** an API key with the `admin` scope, or the dashboard session.\n\n**Test mode:** A test key manages the account's test webhook endpoints, separate from live ones; they receive test events only (a test job's job.* events and webhook.test), signed and retried like live ones.\n\nSend an `idempotency-key` header to retry safely: the same key and body within 1 day never repeat the work.",
        "operationId": "webhook_endpoints.test",
        "parameters": [
          {
            "description": "Webhook endpoint ID (we_…).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "On any POST: your unique key for the request (1–255 printable ASCII characters; a UUID is ideal), kept 24 hours. Retrying with the same key and body never repeats the work: the answer is the first request's result, in its current state.",
            "in": "header",
            "name": "idempotency-key",
            "schema": {
              "maxLength": 255,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "properties": {
                        "data": {
                          "description": "The type's data object (small: a summary plus links)."
                        },
                        "id": {
                          "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                          "type": "string"
                        },
                        "object": {
                          "description": "Always event.",
                          "enum": [
                            "event"
                          ],
                          "type": "string"
                        },
                        "timestamp": {
                          "description": "When it happened.",
                          "format": "date-time",
                          "type": "string"
                        },
                        "type": {
                          "description": "The event type (event types table); new types may be added.",
                          "type": "string"
                        }
                      },
                      "required": [
                        "object",
                        "id",
                        "type",
                        "timestamp",
                        "data"
                      ],
                      "type": "object"
                    },
                    "meta": {
                      "properties": {
                        "client_request_id": {
                          "description": "Your x-client-request-id, echoed; null when you sent none.",
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "credits_charged": {
                          "description": "Always 0: the gateway's own routes are free (a job's items are charged as they end, at their endpoints' prices).",
                          "type": "integer"
                        },
                        "credits_remaining": {
                          "description": "Account balance (the test balance for a test key); null without an account (signup) or when SocialTap could not read it.",
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "mode": {
                          "description": "Mode of the credential that made the request: live, or test for a test key; null without one (signup).",
                          "enum": [
                            "live",
                            "test"
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "request_id": {
                          "description": "Unique request ID; include it when contacting support.",
                          "type": "string"
                        },
                        "warnings": {
                          "description": "Things to act on that did not fail the request. [] when none.",
                          "items": {
                            "properties": {
                              "code": {
                                "description": "Machine-readable warning code (see the warnings list). New codes may be added.",
                                "type": "string"
                              },
                              "doc_url": {
                                "description": "Where to read more (the changelog entry, the endpoint's docs).",
                                "type": "string"
                              },
                              "fields": {
                                "description": "partial_data: the output fields (catalog paths such as metrics.view_count) that are null or [] because part of the data could not be fetched; absent for other codes.",
                                "items": {
                                  "type": "string"
                                },
                                "type": "array"
                              },
                              "message": {
                                "description": "What to do about it.",
                                "type": "string"
                              }
                            },
                            "required": [
                              "code",
                              "message",
                              "doc_url"
                            ],
                            "type": "object"
                          },
                          "type": "array"
                        }
                      },
                      "required": [
                        "request_id",
                        "credits_charged",
                        "credits_remaining",
                        "client_request_id",
                        "mode",
                        "warnings"
                      ],
                      "type": "object"
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Send a webhook.test event to an endpoint",
            "headers": {
              "idempotent-replayed": {
                "$ref": "#/components/headers/idempotent-replayed"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_in_progress": {
                    "$ref": "#/components/examples/idempotency_key_in_progress"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_in_progress`: A request with this Idempotency-Key is still running. Retry after the number of seconds in the retry-after header to get that request's result.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "idempotency_key_reused": {
                    "$ref": "#/components/examples/idempotency_key_reused"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`idempotency_key_reused`: The Idempotency-Key was already used with a different request (another route, or another body). Send a new Idempotency-Key for a different request; reuse a key only to retry the identical request.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "security": [
          {
            "apiKey": []
          },
          {
            "session": []
          }
        ],
        "summary": "Send a webhook.test event to an endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-socialtap-auth": {
          "auth": "key",
          "scope": "admin"
        },
        "x-socialtap-pricing": {
          "max_credits": 0,
          "min_credits": 0,
          "prices": [],
          "unit": "request"
        },
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "idempotency_key_in_progress"
          ]
        }
      }
    },
    "/v1/youtube/comments": {
      "get": {
        "description": "Returns the public top-level comments of a YouTube video, short or live replay, a page at a time: text, author handle and channel, posting time, likes, reply count, and whether the comment is pinned, hearted, edited or written by the creator. Sort newest first (the default, which also supports since and until) or by YouTube's Top ranking, and follow page.next_cursor for more. Accepts every YouTube URL form or a bare 11-character video ID.\n\nReturns `{data, page, meta}`: `data` holds up to 20 `Comment` items (the shared schema, the same on every platform), newest first with sort=newest (the default), YouTube's Top comments ranking with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit (api) per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/youtube/comments/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/youtube/comments/"
        },
        "operationId": "youtube.comments.list",
        "parameters": [
          {
            "description": "YouTube video URL (watch, youtu.be, shorts, live, embed, m./music. hosts) or an 11-character video ID.",
            "example": "jNQXAC9IVRw",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "YouTube video URL (watch, youtu.be, shorts, live, embed, m./music. hosts) or an 11-character video ID.",
              "examples": [
                "https://www.youtube.com/watch?v=jNQXAC9IVRw"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Order of the results. newest (default): newest first. popular: YouTube's Top comments ranking. Either way the video's pinned comment comes first.",
            "example": "newest",
            "in": "query",
            "name": "sort",
            "schema": {
              "default": "newest",
              "description": "Order of the results. newest (default): newest first. popular: YouTube's Top comments ranking. Either way the video's pinned comment comes first.",
              "enum": [
                "newest",
                "popular"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Compared with published_at, which YouTube only shows as a relative label (\"2 days ago\"): the walk stops at the first comment whose label is older, so comments up to one label unit older can be included.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Compared with published_at, which YouTube only shows as a relative label (\"2 days ago\"): the walk stops at the first comment whose label is older, so comments up to one label unit older can be included.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC).",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 20,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 20,
              "maximum": 20,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [
                            "published_at",
                            "metrics.like_count",
                            "metrics.reply_count"
                          ],
                          "author": {
                            "avatar_url": "https://yt3.ggpht.com/i8RqA9tYqbbnOi4mlnYEY7IR3kXAoDqQbM_5Sfzw7OjTubiGsOaTdlrIZmj-I0q0Vup68eqs=s88-c-k-c0x00ffffff-no-rj",
                            "display_name": null,
                            "id": "UCC5NfQ6Mf0dq_eEwv4P_hWA",
                            "is_verified": true,
                            "url": "https://www.youtube.com/channel/UCC5NfQ6Mf0dq_eEwv4P_hWA",
                            "username": "SanDiegoZoo"
                          },
                          "edited_at": null,
                          "id": "UgzuC3zzpRZkjc5Qzsd4AaABAg",
                          "is_by_post_author": false,
                          "is_edited": false,
                          "is_liked_by_author": true,
                          "is_pinned": true,
                          "metrics": {
                            "like_count": 4800000,
                            "reply_count": 1000
                          },
                          "parent_id": null,
                          "platform": "youtube",
                          "platform_specific": {},
                          "post_id": "jNQXAC9IVRw",
                          "published_at": "2020-10-26T18:59:19Z",
                          "text": "We're so honored that the first ever YouTube video was filmed here!",
                          "unknown_fields": [],
                          "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&lc=UgzuC3zzpRZkjc5Qzsd4AaABAg"
                        },
                        {
                          "approximate_fields": [
                            "published_at"
                          ],
                          "author": {
                            "avatar_url": "https://yt3.ggpht.com/U9zdJRwdpo6WwsenxMf6AyMyRMBTWoKsyAWCnJXdbPbNKh-YNEWP3AQRgFto91lckyGCBYENnaw=s88-c-k-c0x00ffffff-no-rj",
                            "display_name": null,
                            "id": "UCjoZE_5A9tO470CK3G6U7dg",
                            "is_verified": false,
                            "url": "https://www.youtube.com/channel/UCjoZE_5A9tO470CK3G6U7dg",
                            "username": "CTwGary"
                          },
                          "edited_at": null,
                          "id": "UgxHbErLhWMUy5GlFnp4AaABAg",
                          "is_by_post_author": false,
                          "is_edited": false,
                          "is_liked_by_author": false,
                          "is_pinned": false,
                          "metrics": {
                            "like_count": 0,
                            "reply_count": 0
                          },
                          "parent_id": null,
                          "platform": "youtube",
                          "platform_specific": {},
                          "post_id": "jNQXAC9IVRw",
                          "published_at": "2026-10-26T18:58:19Z",
                          "text": "I can’t believe it, but it’s 21 years old now",
                          "unknown_fields": [],
                          "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&lc=UgxHbErLhWMUy5GlFnp4AaABAg"
                        },
                        {
                          "approximate_fields": [
                            "published_at"
                          ],
                          "author": {
                            "avatar_url": "https://yt3.ggpht.com/Ar50xvd1O4GCXVttK6DgX0Y0cuhBl2b_HUFQjh-gajKbmS-qjuNAHOT5fw_RX_DS5gzfphkcKAI=s88-c-k-c0x00ffffff-no-rj",
                            "display_name": null,
                            "id": "UCFgjcRO4y8XFQL7E8_TcLlg",
                            "is_verified": false,
                            "url": "https://www.youtube.com/channel/UCFgjcRO4y8XFQL7E8_TcLlg",
                            "username": "Nihal-poke"
                          },
                          "edited_at": null,
                          "id": "UgzLOxwwIAUe0jUI4RR4AaABAg",
                          "is_by_post_author": false,
                          "is_edited": false,
                          "is_liked_by_author": false,
                          "is_pinned": false,
                          "metrics": {
                            "like_count": 0,
                            "reply_count": 0
                          },
                          "parent_id": null,
                          "platform": "youtube",
                          "platform_specific": {},
                          "post_id": "jNQXAC9IVRw",
                          "published_at": "2026-10-26T18:58:19Z",
                          "text": "I watch this video many times 😭",
                          "unknown_fields": [],
                          "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&lc=UgzLOxwwIAUe0jUI4RR4AaABAg"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "youtube",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "jNQXAC9IVRw",
                          "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": true,
                        "next_cursor": "c1.EXAMPLE_CURSOR",
                        "next_cursor_expires_at": "2026-10-26T12:00:00Z",
                        "end_reason": null
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/YoutubeCommentsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Top-level comments of a YouTube video",
        "tags": [
          "YouTube"
        ],
        "x-socialtap-endpoint": "youtube.comments",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 3600,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "newest first",
          "orders": {
            "newest": "newest first",
            "popular": "YouTube's Top comments ranking"
          },
          "page_max": 20,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "api"
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "comment",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/youtube/post": {
      "get": {
        "description": "Returns a public YouTube video, short or live stream: title, description with its hashtags and links, the exact publish time, duration, thumbnail, the channel and any collaborating channels, exact view, like and comment counts, and YouTube's category, tags, chapters and live stream times. Accepts every YouTube video URL form or a bare video ID.\n\nReturns `{data, meta}`: `data` is a `Post` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (api) · 1 credit (page) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/youtube/post/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/youtube/post/"
        },
        "operationId": "youtube.post.get",
        "parameters": [
          {
            "description": "YouTube video, short or live stream URL (watch, youtu.be, shorts, live, embed; m. and music. hosts) or an 11-character video ID.",
            "example": "https://youtube.com/shorts/3cWm9B_0_kI?feature=share",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "YouTube video, short or live stream URL (watch, youtu.be, shorts, live, embed; m. and music. hosts) or an 11-character video ID.",
              "examples": [
                "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [
                          "platform_specific.youtube.author_subscriber_count"
                        ],
                        "author": {
                          "avatar_url": "https://yt3.ggpht.com/nxYrc_1_2f77DoBadyxMTmv7ZpRZapHR5jbuYe7PlPd5cIRJxtNNEYyOC0ZsxaDyJJzXrnJiuDE=s176-c-k-c0x00ffffff-no-rj",
                          "display_name": "MrBeast",
                          "id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
                          "is_verified": true,
                          "url": "https://www.youtube.com/@MrBeast",
                          "username": "MrBeast"
                        },
                        "coauthors": [],
                        "duration_ms": 20000,
                        "hashtags": [],
                        "id": "3cWm9B_0_kI",
                        "is_nsfw": false,
                        "is_pinned": null,
                        "is_sponsored": null,
                        "language": null,
                        "media": [
                          {
                            "alt_text": null,
                            "duration_ms": 20000,
                            "expires_at": null,
                            "height": null,
                            "thumbnail_url": "https://i.ytimg.com/vi/3cWm9B_0_kI/maxresdefault.jpg?sqp=-oaymwEoCIAKENAF8quKqQMcGADwAQH4AbYIgAKAD4oCDAgAEAEYRiBlKA8wDw==&rs=AOn4CLD2HeSN5ZikYi7hBi3SC7913d9CWQ",
                            "type": "video",
                            "url": null,
                            "width": null
                          }
                        ],
                        "mentions": [],
                        "metrics": {
                          "comment_count": 37974,
                          "like_count": 13520602,
                          "quote_count": null,
                          "repost_count": null,
                          "save_count": null,
                          "share_count": null,
                          "view_count": 731918538
                        },
                        "platform": "youtube",
                        "platform_specific": {
                          "youtube": {
                            "author_subscriber_count": 524000000,
                            "category": "Entertainment",
                            "chapters": [],
                            "description_links": [],
                            "is_age_restricted": false,
                            "is_live_now": false,
                            "is_paywalled": false,
                            "is_unlisted": false,
                            "keywords": [],
                            "live_ended_at": null,
                            "live_started_at": null,
                            "scheduled_start_at": null
                          }
                        },
                        "platform_type": "short",
                        "published_at": "2024-12-27T19:00:00Z",
                        "text": null,
                        "thumbnail_url": "https://i.ytimg.com/vi/3cWm9B_0_kI/maxresdefault.jpg?sqp=-oaymwEoCIAKENAF8quKqQMcGADwAQH4AbYIgAKAD4oCDAgAEAEYRiBlKA8wDw==&rs=AOn4CLD2HeSN5ZikYi7hBi3SC7913d9CWQ",
                        "title": "How Many People To Stop Ronaldo?",
                        "type": "video",
                        "unknown_fields": [],
                        "url": "https://www.youtube.com/shorts/3cWm9B_0_kI"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "youtube",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "3cWm9B_0_kI",
                          "url": "https://www.youtube.com/shorts/3cWm9B_0_kI"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/YoutubePostResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "YouTube video, short or live stream with exact counts",
        "tags": [
          "YouTube"
        ],
        "x-socialtap-endpoint": "youtube.post",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "api"
            },
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "page"
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/youtube/posts": {
      "get": {
        "description": "Returns the public uploads of a YouTube channel a page at a time: its videos, shorts or live streams, each with its link, title, thumbnail, length, views and upload time, newest, oldest or most popular first. The newest uploads also carry exact times, view and like counts and descriptions. Accepts a handle, any channel link or a channel ID.\n\nReturns `{data, page, meta}`: `data` holds up to 48 `Post` items (the shared schema, the same on every platform), newest first with sort=newest (the default), oldest first with sort=oldest, YouTube's Popular order (most viewed first) with sort=popular. For the next page repeat the request with `cursor` set to `page.next_cursor` until `page.has_more` is false.\n\n**Pricing:** 1 credit per successful page. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/youtube/posts/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/youtube/posts/"
        },
        "operationId": "youtube.posts.list",
        "parameters": [
          {
            "description": "YouTube channel: a handle with or without the @, any channel link (@handle, /channel/UC…, legacy /c/, /user/ and root vanity links, any tab, m. and music. hosts), a bare UC… channel ID, or c/<name>, user/<name>, vanity/<name>.",
            "example": "@jawed",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "YouTube channel: a handle with or without the @, any channel link (@handle, /channel/UC…, legacy /c/, /user/ and root vanity links, any tab, m. and music. hosts), a bare UC… channel ID, or c/<name>, user/<name>, vanity/<name>.",
              "examples": [
                "@MrBeast"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "The channel tab to list: videos (default), shorts or live (upcoming, live and past streams).",
            "example": "shorts",
            "in": "query",
            "name": "tab",
            "schema": {
              "description": "The channel tab to list: videos (default), shorts or live (upcoming, live and past streams).",
              "enum": [
                "videos",
                "shorts",
                "live"
              ],
              "examples": [
                "shorts"
              ],
              "type": "string"
            }
          },
          {
            "description": "Order of the results. newest (default), popular (most viewed first) or oldest.",
            "example": "",
            "in": "query",
            "name": "sort",
            "schema": {
              "default": "newest",
              "description": "Order of the results. newest (default), popular (most viewed first) or oldest.",
              "enum": [
                "newest",
                "popular",
                "oldest"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Beyond the newest uploads published_at is approximate (\"3 weeks ago\"): uploads up to one label unit older may be included. Not with tab=shorts.",
            "example": "2026-10-01",
            "in": "query",
            "name": "since",
            "schema": {
              "description": "Only items at or after this time: RFC 3339 (2026-10-01T12:00:00Z) or a date (2026-10-01, midnight UTC). On newest-first lists, paging stops when it is reached, so later pages are not fetched or charged. Beyond the newest uploads published_at is approximate (\"3 weeks ago\"): uploads up to one label unit older may be included. Not with tab=shorts.",
              "examples": [
                "2026-10-01"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Not with tab=shorts.",
            "example": "2026-10-08",
            "in": "query",
            "name": "until",
            "schema": {
              "description": "Only items before this time (exclusive): RFC 3339 or a date (midnight UTC). Not with tab=shorts.",
              "examples": [
                "2026-10-08"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Items per page, 1 to the endpoint's page size (its default and maximum; larger values are reduced to it). Omit it: every page costs the same, so a smaller limit means more pages to pay for.",
            "example": 48,
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 48,
              "maximum": 48,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "page.next_cursor from the previous response. Send the same other parameters; omit to start from the first page.",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": [
                        {
                          "approximate_fields": [],
                          "author": {
                            "avatar_url": "https://yt3.googleusercontent.com/uI3VE4PVqvCy0xnWLqMJnEzyBUm3T8VHOCp4ee-1RxdHqKXCdUE_qXYQnpf9AfuEoIPactVyDhM=s900-c-k-c0x00ffffff-no-rj",
                            "display_name": "jawed",
                            "id": "UC4QobU6STFB0P71PMvOGN5A",
                            "is_verified": null,
                            "url": "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A",
                            "username": "jawed"
                          },
                          "coauthors": [],
                          "duration_ms": 19000,
                          "hashtags": [],
                          "id": "jNQXAC9IVRw",
                          "is_nsfw": null,
                          "is_pinned": null,
                          "is_sponsored": null,
                          "language": null,
                          "media": [
                            {
                              "alt_text": null,
                              "duration_ms": 19000,
                              "expires_at": null,
                              "height": 360,
                              "thumbnail_url": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
                              "type": "video",
                              "url": null,
                              "width": 480
                            }
                          ],
                          "mentions": [],
                          "metrics": {
                            "comment_count": null,
                            "like_count": 20117813,
                            "quote_count": null,
                            "repost_count": null,
                            "save_count": null,
                            "share_count": null,
                            "view_count": 446865949
                          },
                          "platform": "youtube",
                          "platform_specific": {
                            "youtube": {
                              "author_subscriber_count": null,
                              "category": null,
                              "chapters": [],
                              "description_links": [
                                "https://www.youtube.com/watch?v=0PT5c1z3LL8",
                                "https://www.youtube.com/watch?v=RRBN_4L09Mg"
                              ],
                              "is_age_restricted": null,
                              "is_live_now": null,
                              "is_paywalled": null,
                              "is_unlisted": null,
                              "keywords": [],
                              "live_ended_at": null,
                              "live_started_at": null,
                              "scheduled_start_at": null
                            }
                          },
                          "platform_type": "video",
                          "published_at": "2005-04-24T03:31:52Z",
                          "text": "Microplastics are accumulating in human brains at an alarming rate\nhttps://www.youtube.com/watch?v=0PT5c1z3LL8\n\n“Nanoplastics and Human Health” with Matthew J Campen, PhD, MSPH\nhttps://www.youtube.com/watch?v=RRBN_4L09Mg\n\n00:00 Intro\n00:05 The cool thing\n00:17 End",
                          "thumbnail_url": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
                          "title": "Me at the zoo",
                          "type": "video",
                          "unknown_fields": [
                            "coauthors",
                            "platform_specific.youtube.keywords",
                            "platform_specific.youtube.chapters"
                          ],
                          "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"
                        }
                      ],
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "youtube",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "UC4QobU6STFB0P71PMvOGN5A",
                          "url": "https://www.youtube.com/@jawed"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      },
                      "page": {
                        "has_more": false,
                        "next_cursor": null,
                        "next_cursor_expires_at": null,
                        "end_reason": "end"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/YoutubePostsResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_cursor": {
                    "$ref": "#/components/examples/invalid_cursor"
                  },
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.\n\n`invalid_cursor`: The cursor is malformed, expired, belongs to another endpoint, or the other parameters differ from the request that issued it. Repeat the original request without cursor to start the list again.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "A YouTube channel's videos, shorts and live streams",
        "tags": [
          "YouTube"
        ],
        "x-socialtap-endpoint": "youtube.posts",
        "x-socialtap-pagination": {
          "cursor_expires_at": "page.next_cursor_expires_at",
          "cursor_param": "cursor",
          "cursor_ttl_s": 3600,
          "has_more": "page.has_more",
          "limit_param": "limit",
          "next_cursor": "page.next_cursor",
          "order": "newest first",
          "orders": {
            "newest": "newest first",
            "oldest": "oldest first",
            "popular": "YouTube's Popular order (most viewed first)"
          },
          "page_max": 48,
          "style": "cursor"
        },
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": ""
            }
          ],
          "unit": "page"
        },
        "x-socialtap-resource": "post",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/youtube/profile": {
      "get": {
        "description": "Returns a public YouTube channel: channel ID, handle, name, description, keywords, avatar, banner, verification badge, country, join date, the links on its About panel with their labels, and its subscriber count with exact video and lifetime view counts. Accepts a handle with or without the @, any channel link with any tab (@handle, /channel/UC…, the legacy /c/, /user/ and root vanity links), or a bare channel ID.\n\nReturns `{data, meta}`: `data` is a `Profile` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/youtube/profile/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/profile/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/profile/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/youtube/profile/"
        },
        "operationId": "youtube.profile.get",
        "parameters": [
          {
            "description": "YouTube channel: a handle with or without the @ (NASA, @NASA), any channel link (youtube.com/@NASA, youtube.com/channel/UC…, the legacy youtube.com/c/<name>, youtube.com/user/<name> and youtube.com/<name> links, with any tab or view after them such as /videos, /playlists, /posts or /about, and m. or music. hosts), a bare UC… channel ID, or c/<name>, user/<name> or vanity/<name>. Handles are case-insensitive. A bare string is always a handle, even one shaped like a video ID.",
            "example": "@NASA",
            "in": "query",
            "name": "handle",
            "required": true,
            "schema": {
              "description": "YouTube channel: a handle with or without the @ (NASA, @NASA), any channel link (youtube.com/@NASA, youtube.com/channel/UC…, the legacy youtube.com/c/<name>, youtube.com/user/<name> and youtube.com/<name> links, with any tab or view after them such as /videos, /playlists, /posts or /about, and m. or music. hosts), a bare UC… channel ID, or c/<name>, user/<name> or vanity/<name>. Handles are case-insensitive. A bare string is always a handle, even one shaped like a video ID.",
              "examples": [
                "@NASA"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "approximate_fields": [
                          "created_at",
                          "metrics.follower_count"
                        ],
                        "avatar_url": "https://yt3.googleusercontent.com/eIf5fNPcIcj9ig-wZBeq4stFy1lgjWTW1nLT5dYlFkHZprZ03QBiMcbpwNMB6XSBjrSFGtAGQg=s900-c-k-c0x00ffffff-no-rj",
                        "banner_url": "https://yt3.googleusercontent.com/y8Srh-oCcilLvBO8jAPI546m1bn0puA5DIvQiBZ1cSxc_rZfKxKSFlTCtoCQCtB6viUf1NGsaQ=w2560-fcrop64=1,00005a57ffffa5a8-k-c0xffffffff-no-nd-rj",
                        "bio": "NASA's mission is to pioneer the future in space exploration, scientific discovery, and aeronautics research.\n\nTo do that, we have worked around the world—and off it—for more than 60 years, searching for answers to fundamental questions about our place in the universe. We're expl…",
                        "category": null,
                        "country_code": null,
                        "created_at": "2008-06-03T07:00:00Z",
                        "display_name": "NASA",
                        "external_links": [
                          {
                            "title": "nasa.gov",
                            "url": "https://www.nasa.gov"
                          },
                          {
                            "title": "X",
                            "url": "https://x.com/nasa"
                          },
                          {
                            "title": "Facebook",
                            "url": "https://www.facebook.com/NASA"
                          }
                        ],
                        "id": "UCLA_DiR1FfKNvjuUpBHmylQ",
                        "is_private": false,
                        "is_verified": true,
                        "location": null,
                        "metrics": {
                          "follower_count": 15100000,
                          "following_count": null,
                          "post_count": 6194,
                          "total_like_count": null,
                          "total_view_count": 1132473139
                        },
                        "platform": "youtube",
                        "platform_specific": {
                          "youtube": {
                            "is_business_email_listed": null,
                            "is_official_artist_channel": false,
                            "is_subscriber_count_hidden": false,
                            "keywords": [
                              "nasa",
                              "space",
                              "iss"
                            ]
                          }
                        },
                        "type": "unknown",
                        "unknown_fields": [],
                        "url": "https://www.youtube.com/@NASA",
                        "username": "NASA"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "youtube",
                        "source": "api",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 0,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "profile",
                          "id": "UCLA_DiR1FfKNvjuUpBHmylQ",
                          "url": "https://www.youtube.com/@NASA"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/YoutubeProfileResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "Public YouTube channel profile and subscriber count",
        "tags": [
          "YouTube"
        ],
        "x-socialtap-endpoint": "youtube.profile",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 1,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": ""
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "profile",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    },
    "/v1/youtube/transcript": {
      "get": {
        "description": "Returns the timed transcript of a public YouTube video, short or live replay: the creator's manual captions when they exist, otherwise YouTube's auto-generated track, in the language you ask for. Videos without any caption track are transcribed from their audio with speech-to-text. Accepts every YouTube URL form (watch, youtu.be, shorts, live, embed, music.) or a bare 11-character video ID.\n\nReturns `{data, meta}`: `data` is a `Transcript` object (the shared schema, the same on every platform). Null means unknown.\n\n**Pricing:** 1 credit (captions) · 2 credits + 2 per started minute of media (asr) per successful request. Failed requests and cache hits are free.\n\n**Docs:** https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/ (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/index.md).",
        "externalDocs": {
          "description": "Endpoint docs (Markdown: https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/index.md)",
          "url": "https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/"
        },
        "operationId": "youtube.transcript.get",
        "parameters": [
          {
            "description": "YouTube video URL (watch, youtu.be, shorts, live, embed, m./music. hosts) or an 11-character video ID.",
            "example": "dQw4w9WgXcQ",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "YouTube video URL (watch, youtu.be, shorts, live, embed, m./music. hosts) or an 11-character video ID.",
              "examples": [
                "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
              ],
              "maxLength": 2048,
              "type": "string"
            }
          },
          {
            "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Selects the caption track; a manual track is preferred over an auto-generated one. Default: the video's original-language manual track, else its auto-generated track.",
            "example": "en",
            "in": "query",
            "name": "lang",
            "schema": {
              "description": "Preferred language: a BCP-47 tag such as en or pt-BR (case-insensitive; _ is read as -). Selects the caption track; a manual track is preferred over an auto-generated one. Default: the video's original-language manual track, else its auto-generated track.",
              "examples": [
                "en"
              ],
              "type": "string"
            }
          },
          {
            "description": "Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent.",
            "in": "query",
            "name": "max_age",
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments[].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole.",
            "in": "query",
            "name": "fields",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 7240. respond-async on any endpoint request runs it as a one-request job: the answer is 202 with the job (Location: its URL) instead of the result.",
            "example": "respond-async",
            "in": "header",
            "name": "prefer",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "description": "Long arrays and strings are shortened for display; real responses are complete.",
                    "summary": "A real response (recorded fixture)",
                    "value": {
                      "data": {
                        "available_languages": [
                          "en",
                          "de-DE",
                          "ja"
                        ],
                        "duration_ms": 213000,
                        "id": "dQw4w9WgXcQ",
                        "is_auto_generated": false,
                        "language": "en",
                        "platform": "youtube",
                        "platform_specific": {},
                        "segments": [
                          {
                            "end_ms": 3040,
                            "start_ms": 1360,
                            "text": "[♪♪♪]"
                          },
                          {
                            "end_ms": 21880,
                            "start_ms": 18640,
                            "text": "♪ We're no strangers to love ♪"
                          },
                          {
                            "end_ms": 26960,
                            "start_ms": 22640,
                            "text": "♪ You know the rules and so do I ♪"
                          }
                        ],
                        "source": "captions",
                        "text": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules and so do I ♪ ♪ A full commitment's what I'm thinking of ♪ ♪ You wouldn't get this from any other guy ♪ ♪ I just wanna tell you how I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let …",
                        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
                      },
                      "meta": {
                        "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
                        "platform": "youtube",
                        "source": "captions",
                        "is_cached": false,
                        "credits_charged": 1,
                        "latency_ms": 511,
                        "fetched_at": "2026-10-25T12:00:00Z",
                        "input": {
                          "kind": "video",
                          "id": "dQw4w9WgXcQ",
                          "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
                        },
                        "credits_remaining": 9999,
                        "client_request_id": null,
                        "warnings": [],
                        "mode": "live"
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/YoutubeTranscriptResponse"
                }
              }
            },
            "description": "OK",
            "headers": {
              "age": {
                "$ref": "#/components/headers/age"
              },
              "allow": {
                "$ref": "#/components/headers/allow"
              },
              "deprecation": {
                "$ref": "#/components/headers/deprecation"
              },
              "link": {
                "$ref": "#/components/headers/link"
              },
              "ratelimit": {
                "$ref": "#/components/headers/ratelimit"
              },
              "ratelimit-policy": {
                "$ref": "#/components/headers/ratelimit-policy"
              },
              "sunset": {
                "$ref": "#/components/headers/sunset"
              },
              "x-client-request-id": {
                "$ref": "#/components/headers/x-client-request-id"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/AsyncAccepted"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_input": {
                    "$ref": "#/components/examples/invalid_input"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`invalid_input`: The request parameters are missing or malformed, or the URL is not a supported link for this endpoint. Fix the parameter named in param (the message says how); for a link of the wrong kind, call the endpoint the message names.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "unauthorized": {
                    "$ref": "#/components/examples/unauthorized"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`unauthorized`: The x-api-key header is missing, unknown or revoked (or, on the dashboard's routes, the session cookie is missing or expired). Send a valid API key in the x-api-key header; without one, get a key at details.signup_url (AI agents: POST details.agent_signup_url).",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "402": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_credits": {
                    "$ref": "#/components/examples/insufficient_credits"
                  },
                  "spend_limit_reached": {
                    "$ref": "#/components/examples/spend_limit_reached"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`insufficient_credits`: The account does not have enough credits for this request. Buy credits (a human pays: details.purchase_url, or details.checkout makes a checkout link), then repeat the request; do not retry automatically.\n\n`spend_limit_reached`: The API key reached its spend limit for the current period; the account may still have credits. Wait until details.resets_at or raise the key's spend limit (PATCH /v1/api_keys/{id}); do not retry automatically.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "forbidden": {
                    "$ref": "#/components/examples/forbidden"
                  },
                  "private_or_unavailable": {
                    "$ref": "#/components/examples/private_or_unavailable"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`forbidden`: The API key is valid but may not make this request: its account is suspended, its scopes do not include the route, it is waiting for its owner's email confirmation, it is past its expiry, or the request came from an IP its allowlist does not include. A running job stops the same way when its account is suspended or the key that created it is revoked or expires. It is about the key, never the item (a private item is private_or_unavailable, also 403): branch on the code. Do what details.reason says: if suspended, contact support; otherwise use a key whose scopes cover the route (details.required_scope), have the owner confirm the emailed link, create a new key, or call from an allowed IP.\n\n`private_or_unavailable`: The item exists but is private, age- or region-gated, or requires a login to view. It shares 403 with forbidden (which is about the key): branch on the code. Only public items can be fetched; do not retry.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "no_transcript": {
                    "$ref": "#/components/examples/no_transcript"
                  },
                  "not_found": {
                    "$ref": "#/components/examples/not_found"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`not_found`: The item does not exist or was deleted. Check the URL or ID; do not retry.\n\n`no_transcript`: The media exists but has no transcript: no caption track and no speech to transcribe. Do not retry; try another language with lang if the platform offers one.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "429": {
            "content": {
              "application/json": {
                "examples": {
                  "rate_limited": {
                    "$ref": "#/components/examples/rate_limited"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`rate_limited`: The account exceeded its runaway-protection ceiling: plans do not limit request rate, but a high per-account safety ceiling stops broken client loops. Support raises it on request. Without an API key (signup, the MCP server's tool listing and find_endpoint), requests are limited per IP address instead. Wait for the number of seconds in the retry-after header, then retry; ask support to raise the ceiling if your sustained traffic needs more (calls without an API key: use one).",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal": {
                    "$ref": "#/components/examples/internal"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`internal`: Unexpected SocialTap error. Retry with backoff; contact support with the request_id if it persists.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "502": {
            "content": {
              "application/json": {
                "examples": {
                  "upstream_error": {
                    "$ref": "#/components/examples/upstream_error"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_error`: The platform failed or returned something unexpected. Retry with backoff; failed requests are free.",
            "headers": {
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          },
          "503": {
            "content": {
              "application/json": {
                "examples": {
                  "overloaded": {
                    "$ref": "#/components/examples/overloaded"
                  },
                  "upstream_blocked": {
                    "$ref": "#/components/examples/upstream_blocked"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`upstream_blocked`: The platform refused every attempt. Retry later with backoff; failed requests are free.\n\n`overloaded`: SocialTap was momentarily at capacity and did not start the request: nothing was fetched or charged. Retry after the number of seconds in the retry-after header; failed requests are free.",
            "headers": {
              "retry-after": {
                "$ref": "#/components/headers/retry-after"
              },
              "x-credits-charged": {
                "$ref": "#/components/headers/x-credits-charged"
              },
              "x-credits-remaining": {
                "$ref": "#/components/headers/x-credits-remaining"
              },
              "x-request-id": {
                "$ref": "#/components/headers/x-request-id"
              }
            }
          }
        },
        "summary": "YouTube video transcript",
        "tags": [
          "YouTube"
        ],
        "x-socialtap-endpoint": "youtube.transcript",
        "x-socialtap-pricing": {
          "cache_hits_free": true,
          "failed_requests_free": true,
          "max_credits": 122,
          "min_credits": 1,
          "prices": [
            {
              "credits": 1,
              "label": "1 credit",
              "max": 1,
              "per": 0,
              "source": "captions"
            },
            {
              "credits": 2,
              "label": "2 credits + 2 per started minute of media",
              "max": 122,
              "per": 2,
              "source": "asr",
              "unit": "media_minute",
              "unit_max": 60
            }
          ],
          "unit": "request"
        },
        "x-socialtap-resource": "transcript",
        "x-socialtap-retry": {
          "failed_requests_free": true,
          "idempotent": true,
          "retry_after_codes": [
            "rate_limited",
            "overloaded"
          ],
          "retry_after_header": "retry-after",
          "retryable_codes": [
            "rate_limited",
            "upstream_blocked",
            "upstream_error",
            "overloaded",
            "internal"
          ]
        }
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "servers": [
    {
      "url": "https://staging-fly.socialtap.dev"
    }
  ],
  "tags": [
    {
      "description": "Public Facebook posts, photos, videos and reels with their counts, video transcripts, and keyword search over Meta's public Ad Library.",
      "name": "Facebook"
    },
    {
      "description": "Public Instagram profiles, posts, reels and carousels, and transcripts of reels and video posts.",
      "name": "Instagram"
    },
    {
      "description": "Public Rumble channel and user profiles, posts (videos, shorts and livestreams), comments and transcripts.",
      "name": "Rumble"
    },
    {
      "description": "Public Threads profiles: account name, bio, links and follower counts.",
      "name": "Threads"
    },
    {
      "description": "Public TikTok profiles with exact follower counts, posts (a video or photo post with its media, sound and engagement counts, or an account's posts), comments on public videos, and transcripts of public videos from creator captions, auto-captions or the audio.",
      "name": "TikTok"
    },
    {
      "description": "Channel profiles, posts (a video's details with exact counts, or a channel's videos, shorts and live streams), and transcripts and comments of public YouTube videos, shorts and live streams.",
      "name": "YouTube"
    },
    {
      "description": "Buy credit packs.",
      "name": "Billing"
    },
    {
      "description": "Live endpoint health.",
      "name": "Status"
    },
    {
      "description": "The account: balance, settings, usage and the credit ledger. Free.",
      "name": "Account"
    },
    {
      "description": "Create, list, update and revoke API keys: scopes, spend limits, expiry, IP allowlists. Free.",
      "name": "API keys"
    },
    {
      "description": "Background jobs and batches: many requests, or one long one, run with the synchronous path's prices and caches.",
      "name": "Jobs"
    },
    {
      "description": "Webhook endpoints: signed (Standard Webhooks), retried deliveries of events.",
      "name": "Webhooks"
    },
    {
      "description": "Events: what happened in the account (jobs ending, credits running low), kept for a while and delivered by webhooks.",
      "name": "Events"
    },
    {
      "description": "Self-serve signup for humans (Google, GitHub or email and password on the sign-in page, then the dashboard) and agents (a test key at once, live after the human confirms). Free.",
      "name": "Signup"
    },
    {
      "description": "The docs themselves: feedback on a page, from readers and agents. Free.",
      "name": "Docs"
    }
  ],
  "webhooks": {
    "api_key.spend_limit_reached": {
      "post": {
        "description": "An API key's request (or job) was refused for its spend limit, the first time in the limit's interval. The body is the event object (its data a SpendLimitReachedData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.api_key_spend_limit_reached",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "api_key_id": {
                        "description": "The key (key_…) whose spend limit was reached.",
                        "type": "string"
                      },
                      "resets_at": {
                        "description": "Start of the next interval, RFC 3339 UTC: the key can spend again then.",
                        "format": "date-time",
                        "type": "string"
                      },
                      "spend_limit": {
                        "description": "Its spend limit.",
                        "properties": {
                          "amount": {
                            "description": "Most credits the key may spend per interval.",
                            "type": "integer"
                          },
                          "interval": {
                            "description": "Calendar day or month, UTC.",
                            "enum": [
                              "day",
                              "month"
                            ],
                            "type": "string"
                          }
                        },
                        "required": [
                          "amount",
                          "interval"
                        ],
                        "type": "object"
                      },
                      "used": {
                        "description": "Credits the key had used this interval (spent plus held by its requests in flight).",
                        "type": "integer"
                      }
                    },
                    "required": [
                      "api_key_id",
                      "spend_limit",
                      "used",
                      "resets_at"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "api_key.spend_limit_reached"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "api_key.spend_limit_reached",
        "tags": [
          "Events"
        ]
      }
    },
    "credits.depleted": {
      "post": {
        "description": "The balance reached 0 (once, until credits are added). The body is the event object (its data a CreditsDepletedData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.credits_depleted",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "balance": {
                        "description": "The balance: 0.",
                        "type": "integer"
                      }
                    },
                    "required": [
                      "balance"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "credits.depleted"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "credits.depleted",
        "tags": [
          "Events"
        ]
      }
    },
    "credits.low": {
      "post": {
        "description": "A balance change took the balance from above the account's low_balance_threshold to at or below it (once per crossing; the owner is emailed too). The body is the event object (its data a CreditsLowData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.credits_low",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "balance": {
                        "description": "The balance after the change that crossed the threshold.",
                        "type": "integer"
                      },
                      "low_balance_threshold": {
                        "description": "The account's low_balance_threshold at the time.",
                        "type": "integer"
                      }
                    },
                    "required": [
                      "balance",
                      "low_balance_threshold"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "credits.low"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "credits.low",
        "tags": [
          "Events"
        ]
      }
    },
    "job.canceled": {
      "post": {
        "description": "A canceled job ended: its running items finished. The body is the event object (its data a JobEventData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.job_canceled",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "created_at": {
                        "format": "date-time",
                        "type": "string"
                      },
                      "credits": {
                        "properties": {
                          "charged": {
                            "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                            "type": "integer"
                          },
                          "max": {
                            "description": "max_credits: the most the job may spend.",
                            "type": "integer"
                          },
                          "reserved": {
                            "description": "Credits its running pages may still use (0 once the job ends).",
                            "type": "integer"
                          }
                        },
                        "required": [
                          "max",
                          "reserved",
                          "charged"
                        ],
                        "type": "object"
                      },
                      "finished_at": {
                        "format": "date-time",
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "id": {
                        "type": "string"
                      },
                      "metadata": {
                        "additionalProperties": {
                          "type": "string"
                        },
                        "type": "object"
                      },
                      "object": {
                        "enum": [
                          "job"
                        ],
                        "type": "string"
                      },
                      "request_counts": {
                        "properties": {
                          "canceled": {
                            "type": "integer"
                          },
                          "expired": {
                            "type": "integer"
                          },
                          "failed": {
                            "type": "integer"
                          },
                          "queued": {
                            "description": "Not started.",
                            "type": "integer"
                          },
                          "running": {
                            "description": "Started (fetching, waiting for a retry or walking pages).",
                            "type": "integer"
                          },
                          "succeeded": {
                            "type": "integer"
                          },
                          "total": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "total",
                          "queued",
                          "running",
                          "succeeded",
                          "failed",
                          "canceled",
                          "expired"
                        ],
                        "type": "object"
                      },
                      "results_url": {
                        "description": "Every result as JSON Lines, the job's signed results_url: it works without the API key for 1 hour after the event; GET url for a fresh one.",
                        "type": "string"
                      },
                      "status": {
                        "enum": [
                          "queued",
                          "running",
                          "canceling",
                          "completed",
                          "canceled",
                          "expired"
                        ],
                        "type": "string"
                      },
                      "url": {
                        "description": "GET this (with your API key) for the job.",
                        "type": "string"
                      }
                    },
                    "required": [
                      "object",
                      "id",
                      "status",
                      "request_counts",
                      "credits",
                      "metadata",
                      "created_at",
                      "finished_at",
                      "url",
                      "results_url"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "job.canceled"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "job.canceled",
        "tags": [
          "Events"
        ]
      }
    },
    "job.completed": {
      "post": {
        "description": "A job ended with every item ended (check request_counts: items fail individually). The body is the event object (its data a JobEventData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.job_completed",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "created_at": {
                        "format": "date-time",
                        "type": "string"
                      },
                      "credits": {
                        "properties": {
                          "charged": {
                            "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                            "type": "integer"
                          },
                          "max": {
                            "description": "max_credits: the most the job may spend.",
                            "type": "integer"
                          },
                          "reserved": {
                            "description": "Credits its running pages may still use (0 once the job ends).",
                            "type": "integer"
                          }
                        },
                        "required": [
                          "max",
                          "reserved",
                          "charged"
                        ],
                        "type": "object"
                      },
                      "finished_at": {
                        "format": "date-time",
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "id": {
                        "type": "string"
                      },
                      "metadata": {
                        "additionalProperties": {
                          "type": "string"
                        },
                        "type": "object"
                      },
                      "object": {
                        "enum": [
                          "job"
                        ],
                        "type": "string"
                      },
                      "request_counts": {
                        "properties": {
                          "canceled": {
                            "type": "integer"
                          },
                          "expired": {
                            "type": "integer"
                          },
                          "failed": {
                            "type": "integer"
                          },
                          "queued": {
                            "description": "Not started.",
                            "type": "integer"
                          },
                          "running": {
                            "description": "Started (fetching, waiting for a retry or walking pages).",
                            "type": "integer"
                          },
                          "succeeded": {
                            "type": "integer"
                          },
                          "total": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "total",
                          "queued",
                          "running",
                          "succeeded",
                          "failed",
                          "canceled",
                          "expired"
                        ],
                        "type": "object"
                      },
                      "results_url": {
                        "description": "Every result as JSON Lines, the job's signed results_url: it works without the API key for 1 hour after the event; GET url for a fresh one.",
                        "type": "string"
                      },
                      "status": {
                        "enum": [
                          "queued",
                          "running",
                          "canceling",
                          "completed",
                          "canceled",
                          "expired"
                        ],
                        "type": "string"
                      },
                      "url": {
                        "description": "GET this (with your API key) for the job.",
                        "type": "string"
                      }
                    },
                    "required": [
                      "object",
                      "id",
                      "status",
                      "request_counts",
                      "credits",
                      "metadata",
                      "created_at",
                      "finished_at",
                      "url",
                      "results_url"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "job.completed"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "job.completed",
        "tags": [
          "Events"
        ]
      }
    },
    "job.expired": {
      "post": {
        "description": "A job reached its deadline; its unfinished items expired. The body is the event object (its data a JobEventData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.job_expired",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "created_at": {
                        "format": "date-time",
                        "type": "string"
                      },
                      "credits": {
                        "properties": {
                          "charged": {
                            "description": "Credits charged so far, each page once (items' prices; failed items are free).",
                            "type": "integer"
                          },
                          "max": {
                            "description": "max_credits: the most the job may spend.",
                            "type": "integer"
                          },
                          "reserved": {
                            "description": "Credits its running pages may still use (0 once the job ends).",
                            "type": "integer"
                          }
                        },
                        "required": [
                          "max",
                          "reserved",
                          "charged"
                        ],
                        "type": "object"
                      },
                      "finished_at": {
                        "format": "date-time",
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "id": {
                        "type": "string"
                      },
                      "metadata": {
                        "additionalProperties": {
                          "type": "string"
                        },
                        "type": "object"
                      },
                      "object": {
                        "enum": [
                          "job"
                        ],
                        "type": "string"
                      },
                      "request_counts": {
                        "properties": {
                          "canceled": {
                            "type": "integer"
                          },
                          "expired": {
                            "type": "integer"
                          },
                          "failed": {
                            "type": "integer"
                          },
                          "queued": {
                            "description": "Not started.",
                            "type": "integer"
                          },
                          "running": {
                            "description": "Started (fetching, waiting for a retry or walking pages).",
                            "type": "integer"
                          },
                          "succeeded": {
                            "type": "integer"
                          },
                          "total": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "total",
                          "queued",
                          "running",
                          "succeeded",
                          "failed",
                          "canceled",
                          "expired"
                        ],
                        "type": "object"
                      },
                      "results_url": {
                        "description": "Every result as JSON Lines, the job's signed results_url: it works without the API key for 1 hour after the event; GET url for a fresh one.",
                        "type": "string"
                      },
                      "status": {
                        "enum": [
                          "queued",
                          "running",
                          "canceling",
                          "completed",
                          "canceled",
                          "expired"
                        ],
                        "type": "string"
                      },
                      "url": {
                        "description": "GET this (with your API key) for the job.",
                        "type": "string"
                      }
                    },
                    "required": [
                      "object",
                      "id",
                      "status",
                      "request_counts",
                      "credits",
                      "metadata",
                      "created_at",
                      "finished_at",
                      "url",
                      "results_url"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "job.expired"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "job.expired",
        "tags": [
          "Events"
        ]
      }
    },
    "webhook.test": {
      "post": {
        "description": "Sent by POST /v1/webhook_endpoints/{id}/test to that endpoint only. The body is the event object (its data a WebhookTestData); verify webhook-signature before trusting it (Standard Webhooks).",
        "operationId": "webhooks.webhook_test",
        "parameters": [
          {
            "description": "The event ID (evt_…), the same on every retry: deduplicate deliveries on it.",
            "in": "header",
            "name": "webhook-id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When this attempt was signed, in Unix seconds: reject deliveries outside your tolerance (replays).",
            "in": "header",
            "name": "webhook-timestamp",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Space-separated v1,SIGNATURE entries, each the base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, with one active secret (two during a rotation): accept the delivery when one matches.",
            "in": "header",
            "name": "webhook-signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "data": {
                    "description": "The type's data object (small: a summary plus links).",
                    "properties": {
                      "webhook_endpoint_id": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "webhook_endpoint_id"
                    ],
                    "type": "object"
                  },
                  "id": {
                    "description": "The event ID (evt_…): the webhook-id header of every delivery, the same on retries. Deduplicate on it.",
                    "type": "string"
                  },
                  "object": {
                    "description": "Always event.",
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "When it happened.",
                    "format": "date-time",
                    "type": "string"
                  },
                  "type": {
                    "description": "The event type (event types table); new types may be added.",
                    "enum": [
                      "webhook.test"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "object",
                  "id",
                  "type",
                  "timestamp",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Any other answer is retried on the schedule; 410 disables the endpoint."
          }
        },
        "summary": "webhook.test",
        "tags": [
          "Events"
        ]
      }
    }
  }
}