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.
ShortsIntel
Create a key

API referenceBreakdowns

Read a breakdown's digest

GET /v1/breakdowns/{id}/digest

A Breakdown's Digest, answered as GET /v1/research/{id}/digest answers it.

Open in Playground (no API Key needed)

Price

Free, forever. Collection is the only thing charged.

Parameters

NameInTypeRequiredDefaultDescription
idpathstring Required—Breakdown id — the id of its Run.
as_ofquerystring one of run, latestOptionalrunAccepted for symmetry with the other research reads, so one basis can be passed to all of them, and validated like theirs. A digest is always served as run whichever you pass: it is what a model wrote about the shortlist the research collected, and there is no fresher one to serve.

Responses

200 OK

The digest, with the context it was computed in. as_of always reads run here: a digest is what a model wrote about the shortlist the research collected, not a number joined to a snapshot, so there is no fresher one to serve.

object

A research's digest with the intent, keywords and coverage it was computed in — and none of the evidence.

  • digest object required
    • summary string required Two or three sentences answering the intent directly: what is working on this topic right now, across the videos analysed.
    • themes array of object required items 1 to 8
      • name string required Short label, three or four words.
      • share number required value 0 to 1 Fraction of the analysed videos that belong to this theme, 0-1.
      • description string required What the videos in this theme have in common.
      • video_ids array of string required video_id keys (platform:id) of the analysed videos that belong to this theme, exactly as given in the evidence.
    • hooks array of object required items at most 12
      • text string required The opening line, quoted VERBATIM from the evidence. Never paraphrase, never invent.
      • video_id string required video_id key (platform:id) of the video this hook is quoted from, exactly as given in the evidence.
      • hook_type string required The kind of hook, e.g. question, claim, negation, stat.
      • why_it_works string required One sentence.
      • template string length at least 1 The verbatim hook with its specifics (product, number, mistake, outcome, audience) replaced by short bracketed slots, every other word kept as spoken, e.g. "Stop [mistake] if you want [outcome]".
      • lift object nullable The lift_tables.hook_type row for the quoted video's analysed hook type, attached in code (never written by the model). Null when that video has no analysed hook type.
        • value string required The analysed hook type, or format + hook type, the row is keyed by.
        • video_count integer required
        • median_views number required nullable
        • median_engagement_rate number required nullable
        • views_lift number required nullable
        • engagement_lift number required nullable
        • low_confidence boolean required
    • sentiment object required
      • positive number required value 0 to 1
      • neutral number required value 0 to 1
      • negative number required value 0 to 1
      • note string required One sentence on what drives the distribution.
    • angles array of object required items 1 to 8
      • angle string required A content angle worth trying.
      • rationale string required Why the evidence supports it, referencing what was seen.
    • formulas array of object items at most 5
      • name string required Short label, three to five words.
      • recipe string required One line saying how to make it: the format, how it opens, and the order of its beats.
      • visual_format string required The visual format, copied exactly as it appears in lift_tables.visual_format.
      • hook_type string required The hook type, copied exactly as it appears in lift_tables.hook_type.
      • structure string required The beat structure the example videos share, as short beats joined by arrows, e.g. "problem → demo → result → CTA".
      • video_ids array of string required Up to 3 video_id keys (platform:id) of analysed videos that follow this formula, best performing first, exactly as given in the evidence.
      • lift object required nullable The lift_tables.format_hook row for this formula's visual format and hook type, attached in code (never written by the model): its video_count and lifts. The lift is for the format + hook type pair only; the structure is not bucketed. Null when no analysed video has that pair.
        • value string required The analysed hook type, or format + hook type, the row is keyed by.
        • video_count integer required
        • median_views number required nullable
        • median_engagement_rate number required nullable
        • views_lift number required nullable
        • engagement_lift number required nullable
        • low_confidence boolean required
    • gaps array of object items at most 5 Up to 5 things the audience asks for in the top 10 videos' comments that no analysed video addresses, each with verbatim quoted comments (and the video they came from) and a suggested angle. Empty when no comments were available. Absent on research recorded before gaps existed.
      • ask string required What the audience asks for or complains about, in one sentence, in your own words.
      • comments array of object required items 1 to 3
        • text string required A comment quoted VERBATIM from <comments>, character for character. Never paraphrase, never invent.
        • video_id string required video_id key (platform:id) of the video this comment was left under, exactly as given in <comments>.
      • angle string required A video someone could make that answers this ask, in one sentence.
  • digest_version integer required
  • lift_tables object Lift tables computed in code over the analysed videos: per visual format, hook type and length bucket, the video count, median views and engagement rate, and lift versus the whole set's median. The Digest quotes lifts only from these. Absent on research recorded before they existed.
    • basis string one of set_median, creator_median
    • set object required
      • video_count integer required
      • median_views number required nullable
      • median_engagement_rate number required nullable
    • visual_format array of object required
      • value string required The visual format, hook type, length bucket, or <format> + <hook type>.
      • video_count integer required
      • median_views number required nullable
      • median_engagement_rate number required nullable (likes + comments + shares + saves) / views.
      • views_lift number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown.
      • engagement_lift number required nullable
      • low_confidence boolean required True when the row rests on fewer than 3 videos.
    • hook_type array of object required
      • value string required The visual format, hook type, length bucket, or <format> + <hook type>.
      • video_count integer required
      • median_views number required nullable
      • median_engagement_rate number required nullable (likes + comments + shares + saves) / views.
      • views_lift number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown.
      • engagement_lift number required nullable
      • low_confidence boolean required True when the row rests on fewer than 3 videos.
    • length array of object required
      • value string required The visual format, hook type, length bucket, or <format> + <hook type>.
      • video_count integer required
      • median_views number required nullable
      • median_engagement_rate number required nullable (likes + comments + shares + saves) / views.
      • views_lift number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown.
      • engagement_lift number required nullable
      • low_confidence boolean required True when the row rests on fewer than 3 videos.
    • format_hook array of object Visual format and hook type together, value as <format> + <hook type>: the rows the Digest's formulas take their lift from. Absent on research recorded before it existed.
      • value string required The visual format, hook type, length bucket, or <format> + <hook type>.
      • video_count integer required
      • median_views number required nullable
      • median_engagement_rate number required nullable (likes + comments + shares + saves) / views.
      • views_lift number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown.
      • engagement_lift number required nullable
      • low_confidence boolean required True when the row rests on fewer than 3 videos.
  • mode string one of keywords, creators What the research was seeded with: keywords (an intent) or creators (a breakdown). Absent means keywords.
  • intent string
  • keywords array of string
  • keyword_rationale string
  • coverage map of string required
  • as_of string required one of run, latest Which snapshots the numbers come from: run is what the research itself saw, frozen, so a read always agrees with the digest; latest is the newest snapshot this API holds for each video.

200 · The digest, with the context it was computed in. `as_of` always reads `run` here: a digest is what a model wrote about the shortlist the research collected, not a number joined to a snapshot, so there is no fresher one to serve.

{
  "digest": {
    "summary": "Cold plunge videos are travelling on measured personal diaries rather than on science explainers. The videos that break out open on an unimpressive first number and pay it off with a later one, and keep the discomfort on camera instead of cutting around it. Sentiment is broadly positive, with the negative share concentrated on the cost of equipment.",
    "themes": [
      {
        "name": "30-day diaries",
        "share": 0.45,
        "description": "One creator, one tub, a counter on screen, and the change stated as a number rather than a feeling.",
        "video_ids": [
          "tiktok:7300000000000000000"
        ]
      },
      {
        "name": "Before-workout plunging",
        "share": 0.2,
        "description": "Shorter clips arguing about timing relative to training, usually with a gym setting.",
        "video_ids": [
          "tiktok:7300000000000000042"
        ]
      }
    ],
    "hooks": [
      {
        "text": "Day one I lasted eleven seconds.",
        "video_id": "tiktok:7300000000000000000",
        "hook_type": "stat",
        "why_it_works": "An unimpressive concrete number sets up a payoff the viewer stays for.",
        "template": "Day one I lasted [small number] [unit].",
        "lift": {
          "value": "STORY",
          "video_count": 9,
          "median_views": 1840000,
          "median_engagement_rate": 0.0912,
          "views_lift": 1.6,
          "engagement_lift": 1.21,
          "low_confidence": false
        }
      }
    ],
    "sentiment": {
      "positive": 0.62,
      "neutral": 0.23,
      "negative": 0.15,
      "note": "Enthusiasm for the routine itself; the negative share is almost entirely the price of a tub."
    },
    "angles": [
      {
        "angle": "Open on the day-30 number and work backwards to day one.",
        "rationale": "Every diary in the shortlist that led with the outcome outperformed the ones that led with the method."
      }
    ],
    "gaps": [
      {
        "ask": "Viewers want a cold plunge setup that does not cost hundreds.",
        "comments": [
          {
            "text": "ok but what do I do if I can't afford a 600 dollar tub",
            "video_id": "tiktok:7300000000000000000"
          }
        ],
        "angle": "A 30-day diary on a chest freezer or bathtub build, with the receipt on screen."
      }
    ]
  },
  "digest_version": 2,
  "mode": "keywords",
  "intent": "why are cold plunge videos taking off",
  "keywords": [
    "cold plunge",
    "ice bath",
    "cold exposure",
    "cold plunge routine"
  ],
  "keyword_rationale": "The intent is about a practice rather than a product, so the keywords cover the practice and its two common synonyms.",
  "coverage": {
    "tiktok": "complete",
    "instagram": "partial"
  },
  "as_of": "run"
}

400 Bad Request

invalid_request — an unknown as_of.

Code: invalid_request. 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, 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.
  • 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 What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • 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.

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`as_of` must be one of run, latest.",
  "retryable": false,
  "action": "Fix the field named in `detail`, then send the corrected request."
}

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, 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.
  • 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 What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • 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, 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.
  • 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 What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • 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 research with that id for this Customer.",
  "retryable": false,
  "action": "Check the id or handle; list your resources to find the right one."
}

409 Conflict

run_not_ready — the research is still running, or failed with nothing to serve. If it is still running, poll GET /v1/runs/{id} and read again once it settles; a failed research never becomes readable.

Code: run_not_ready. 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, 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.
  • 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 What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • 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.

409 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/run_not_ready",
  "title": "Run not ready",
  "status": 409,
  "code": "run_not_ready",
  "detail": "Research `run_c07a41bb92` is still running. Poll GET /v1/runs/run_c07a41bb92 until it reaches a terminal status.",
  "retryable": true,
  "action": "Poll the Run until it settles, then read again. If it failed, start a new Run."
}

Request samples

Use ShortsIntel to read a breakdown's digest.

- id: id_example
- as_of: run

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.