Skip to content
For AI agents: a documentation index is available at /llms.txt. Every docs page is also available as markdown: add .md to its URL. To connect, read /agents.md.

API referenceWebhooks

Get a webhook endpoint

GET /v1/webhooks/{id}

One endpoint.

Price

Free.

Parameters

NameInTypeRequiredDefaultDescription
idpathstring Required—Webhook endpoint id.

Responses

200 OK

{ webhook }.

object

  • webhook object required
    • id string required
    • url string required
    • status string required one of pending, active, failed, disabled
    • description string required nullable
    • secret_prefix string required The first characters of the signing secret, to tell two apart.
    • previous_secret_expires_at string required nullable
    • created_at string required
    • activated_at string required nullable
    • last_delivery_at string required nullable

401 Unauthorized

missing_authorization, invalid_key, key_revoked, key_expired or invalid_token.

Codes: missing_authorization, invalid_key, key_revoked, key_expired, invalid_token. The problem body and every code are on Errors.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.

  • type string required
  • title string required
  • status integer required
  • code string required one of missing_authorization, invalid_key, key_revoked, key_expired, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, key_scope_insufficient, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, focus_unsupported_kind, not_found, comment_not_found, video_too_long, feature_unavailable, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, max_credits_exceeded, key_spend_cap_exceeded, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_error Stable machine-readable code.
  • detail string
  • errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
    • path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
    • message string required What is wrong with that field.
  • request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
  • retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
  • action string required The next step, in one sentence.
  • remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
  • retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
  • expired_at string When the key expired. On key_expired.
  • resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
  • limit integer The limit that was hit, on the *_limit_exceeded codes.
  • running integer Runs in flight. On concurrency_limit_exceeded.
  • active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
  • requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
  • count integer Collections held. On collection_limit_exceeded.
  • balance_credits integer The Balance, in Credits. On insufficient_balance.
  • required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
  • max_credits integer The cap the call sent. On max_credits_exceeded.
  • estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
  • cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
  • spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
  • reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
  • endpoints array of string The sources that could not answer. On source_unavailable.
  • endpoint string The source that could not answer. On source_unavailable.
  • candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
  • supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
  • feature string The switched-off option, e.g. download. On feature_unavailable.
  • duration_seconds number The video's length. On video_too_long.
  • max_duration_seconds number The longest video accepted. On video_too_long.
  • overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
  • scope string always read_only The key's scope. On key_scope_insufficient.
  • required string always full The scope the call needs. On key_scope_insufficient.
  • collection_id string The Collection that already has the name. On collection_name_taken.
  • collection_kind string The Collection's kind. On collection_kind_mismatch.
  • kind string The kind that was offered. On collection_kind_mismatch.
  • run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
  • reason string A short machine-readable reason, where a code has several.
  • reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
  • run object The Run, on a failed Run's body, so its id is kept.
    • id string required
    • kind string required What was run, e.g. video_lookup.
    • status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
    • created_at string required RFC 3339.
    • completed_at string required nullable Null while the Run is still running.
    • charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    • list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
    • cached boolean required True when a stored result answered without a fresh fetch.
    • progress object A running Research's stage and counts so far, such as analysed of shortlisted; a count is absent until known. Absent once the Run settles and on other kinds.
      • stage string required one of keywords, searching, reading_creators, filtering, analysing, writing_digest
      • keywords integer value at least 0
      • creators integer value at least 0
      • creators_read integer value at least 0
      • searches integer value at least 0
      • found integer value at least 0
      • judged integer value at least 0
      • kept integer value at least 0
      • dropped_off_topic integer value at least 0
      • dropped_unsure integer value at least 0
      • shortlisted integer value at least 0
      • analysed integer value at least 0
      • updated_at string required
  • error object The same problem, nested, on a failed Run's body.

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console.",
  "retryable": false,
  "action": "Check the whole key was copied, or create a new key in the console."
}

404 Not Found

not_found.

Code: not_found. The problem body and every code are on Errors.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.

  • type string required
  • title string required
  • status integer required
  • code string required one of missing_authorization, invalid_key, key_revoked, key_expired, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, key_scope_insufficient, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, focus_unsupported_kind, not_found, comment_not_found, video_too_long, feature_unavailable, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, max_credits_exceeded, key_spend_cap_exceeded, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_error Stable machine-readable code.
  • detail string
  • errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
    • path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
    • message string required What is wrong with that field.
  • request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
  • retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
  • action string required The next step, in one sentence.
  • remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
  • retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
  • expired_at string When the key expired. On key_expired.
  • resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
  • limit integer The limit that was hit, on the *_limit_exceeded codes.
  • running integer Runs in flight. On concurrency_limit_exceeded.
  • active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
  • requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
  • count integer Collections held. On collection_limit_exceeded.
  • balance_credits integer The Balance, in Credits. On insufficient_balance.
  • required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
  • max_credits integer The cap the call sent. On max_credits_exceeded.
  • estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
  • cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
  • spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
  • reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
  • endpoints array of string The sources that could not answer. On source_unavailable.
  • endpoint string The source that could not answer. On source_unavailable.
  • candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
  • supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
  • feature string The switched-off option, e.g. download. On feature_unavailable.
  • duration_seconds number The video's length. On video_too_long.
  • max_duration_seconds number The longest video accepted. On video_too_long.
  • overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
  • scope string always read_only The key's scope. On key_scope_insufficient.
  • required string always full The scope the call needs. On key_scope_insufficient.
  • collection_id string The Collection that already has the name. On collection_name_taken.
  • collection_kind string The Collection's kind. On collection_kind_mismatch.
  • kind string The kind that was offered. On collection_kind_mismatch.
  • run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
  • reason string A short machine-readable reason, where a code has several.
  • reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
  • run object The Run, on a failed Run's body, so its id is kept.
    • id string required
    • kind string required What was run, e.g. video_lookup.
    • status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
    • created_at string required RFC 3339.
    • completed_at string required nullable Null while the Run is still running.
    • charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    • list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
    • cached boolean required True when a stored result answered without a fresh fetch.
    • progress object A running Research's stage and counts so far, such as analysed of shortlisted; a count is absent until known. Absent once the Run settles and on other kinds.
      • stage string required one of keywords, searching, reading_creators, filtering, analysing, writing_digest
      • keywords integer value at least 0
      • creators integer value at least 0
      • creators_read integer value at least 0
      • searches integer value at least 0
      • found integer value at least 0
      • judged integer value at least 0
      • kept integer value at least 0
      • dropped_off_topic integer value at least 0
      • dropped_unsure integer value at least 0
      • shortlisted integer value at least 0
      • analysed integer value at least 0
      • updated_at string required
  • error object The same problem, nested, on a failed Run's body.

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No webhook endpoint with that id for this Customer.",
  "retryable": false,
  "action": "Check the id or handle; list your resources to find the right one."
}
  • Webhooks: The events we send, how to verify a signature, what happens when your endpoint is down, and how to rotate a secret.

Request samples

Use ShortsIntel to get a webhook endpoint.

- id: whe_6d2f10ab44

Tell me what it will cost before you run it, then summarise what you find.

If you don't have ShortsIntel tools, don't guess: read https://www.shortsintel.com/agents.md, follow it to connect, then retry this request.

200 · `{ webhook }`.

{
  "webhook": {
    "id": "whe_6d2f10ab44",
    "url": "https://hooks.example.com/shortsintel",
    "status": "active",
    "description": "production receiver",
    "secret_prefix": "whsec_a1b2c3",
    "previous_secret_expires_at": null,
    "created_at": "2026-09-08T09:14:02.418Z",
    "activated_at": "2026-09-08T09:14:03.006Z",
    "last_delivery_at": "2026-09-08T09:14:03.006Z"
  }
}