List run items (GET /v1/runs/{id}/items)

GET/v1/runs/{id}/items

The items a Run delivered, each with its own status, charge and — when it failed — the problem body explaining why. This is how a partial Run says what did and did not arrive.

Price

Free: the charge happened once, when the work did.

Parameters

Name	In	Type	Required	Default	Description
`id`	path	`string`	Required	—	Run id.
`limit`	query	`integer`min 1; max 100	Optional	`25`	Items per page.
`cursor`	query	`string`	Optional	—	Opaque `next_cursor` from the previous page.
`type`	query	`string`one of `videos`, `creators`, `hashtags`, `sounds`, `ads`	Optional	—	`videos`, `creators`, `hashtags`, `sounds` or `ads` (singular accepted too). A Meta ad search has one `ad` item per Ad delivered, with the Ad as its `payload`.

Responses

200 OK

{ items, next_cursor }.

object

itemsarray of objectrequired
- idstringrequired
- typestringrequiredvideo, creator, hashtag or sound.
- statusstringrequiredone of pending, completed, failed
- positionintegerrequired
- charge_creditsintegerrequired
- cachedbooleanrequired
- videoobjectrequirednullable
  platformstringrequired
  idstringrequired
  urlstringrequirednullable
  descriptionstringrequired
- subject_idstringnullable
- payloadany
- errorobjectWhy this one item failed.
  typestringrequired
  titlestringrequired
  statusintegerrequired
  codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, 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_errorStable machine-readable code.
  detailstring
next_cursorstringrequirednullablePass back as cursor. Null on the last page.

200 · `{ items, next_cursor }`.

{
  "items": [
    {
      "id": "itm_0a91cc37e2",
      "type": "video",
      "status": "completed",
      "position": 0,
      "charge_credits": 0,
      "cached": false,
      "video": {
        "platform": "tiktok",
        "id": "7300000000000000000",
        "url": "https://www.tiktok.com/@someone/video/7300000000000000000",
        "description": "3 minutes at 4°C every morning for 30 days. Here is what actually changed. #coldplunge #recovery"
      }
    },
    {
      "id": "itm_0a91cc37f5",
      "type": "video",
      "status": "failed",
      "position": 37,
      "charge_credits": 0,
      "cached": false,
      "video": {
        "platform": "tiktok",
        "id": "7300000000000000077",
        "url": "https://www.tiktok.com/@thirdone/video/7300000000000000077",
        "description": "cold plunge fails compilation"
      },
      "error": {
        "type": "https://www.shortsintel.com/docs/reference/errors/media_unavailable",
        "title": "Media unavailable",
        "status": 502,
        "code": "media_unavailable",
        "detail": "The video file could not be fetched, so it was not analysed and not charged for."
      }
    }
  ],
  "next_cursor": "eyJwIjozOH0"
}

400 Bad Request

invalid_request for a cursor that is not a next_cursor this API issued. Nothing is charged.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, 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_errorStable machine-readable code.
detailstring

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`cursor` is not a cursor this API issued. Pass back the `next_cursor` from the previous page."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, 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_errorStable machine-readable code.
detailstring

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."
}

404 Not Found

not_found — including anything belonging to another Customer.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

typestringrequired
titlestringrequired
statusintegerrequired
codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, 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_errorStable machine-readable code.
detailstring

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such resource for this Customer."
}

Request samples

curl "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b/items?limit=25&type=videos" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b/items?limit=25&type=videos",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b/items?limit=25&type=videos",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

Pagination: Following next_cursor through a list.

Price

Parameters

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Request samples

Related guides