Feed data

GET /v1/feeds lists the published feeds your organization subscribes to, and GET /v1/feeds/{feed}/data lists the files a feed has collected, each with a download link. Use them to pull a running feed's output into your own pipeline. To check a build's schema and a few of its rows, use Sample rows.

Listing your feeds

curl "https://feedbuilder.usestring.ai/v1/feeds" \
  -H "Authorization: Bearer $STRING_FEED_BUILDER_KEY"

{
  "object": "list",
  "data": [
    { "object": "feed", "name": "example_laptops", "data_available": true }
  ]
}

A feed appears only while your organization holds an active subscription to it. A feed with no subscription is not listed.

Listing a feed's files

curl "https://feedbuilder.usestring.ai/v1/feeds/example_laptops/data?page_size=100&expires_in=3600" \
  -H "Authorization: Bearer $STRING_FEED_BUILDER_KEY"

Trimmed to one file, for a subscription using the default export format:

{
  "object": "list",
  "feed": "example_laptops",
  "data": [
    {
      "object": "feed_data",
      "path": "101/part-0.json.gz",
      "size": 48213,
      "updated_at": "2026-10-18T06:12:40Z",
      "url": "https://…",
      "expires_at": "2026-10-18T07:12:41Z"
    }
  ],
  "truncated": true,
  "next_page_token": "…"
}

If your subscription has a delivery format, the listing contains that format's files, using its file names, columns, row selection, encoding and compression. For example, a subscription can deliver a zip containing a JSON array instead of the default gzipped JSONL. Each file's path is its run followed by its file name.

Filtering by date

To select files written on one day, send both time bounds:

curl --get "https://feedbuilder.usestring.ai/v1/feeds/example_laptops/data" \
  -H "Authorization: Bearer $STRING_FEED_BUILDER_KEY" \
  --data-urlencode "updated_after=2026-10-18T00:00:00Z" \
  --data-urlencode "updated_before=2026-10-19T00:00:00Z"

The response has the same shape as the listing above. The bounds filter file timestamps, not individual rows. They narrow the files returned without reducing the number of pages to examine. Keep following next_page_token even when a filtered page is empty, until truncated is false.

Downloading a file

For a default export, set FILE_URL to a signed url from the listing and download it without an Authorization header:

curl --fail -o part-0.json.gz "$FILE_URL"

The default export is gzipped JSONL. Gunzip it, then parse one JSON object per line.

For files in your delivery format, url is a relative API path beginning with /v1/feeds/. Set FILE_URL_PATH to that value, prepend https://feedbuilder.usestring.ai, and authenticate with the same API key. This example saves a formatted file named laptops.zip:

curl --fail -o laptops.zip "https://feedbuilder.usestring.ai$FILE_URL_PATH" \
  -H "Authorization: Bearer $STRING_FEED_BUILDER_KEY"

Decode the result using your subscription's encoding and compression. These links do not expire and have no expires_at; expires_in does not change them. Send your key only to the API host, never to a signed-link host.

Downloading through the API host

If your network cannot reach a signed link's host, download the same file through GET /v1/feeds/{feed}/download. It requires your API key and the file's path from the listing:

curl --fail --get "https://feedbuilder.usestring.ai/v1/feeds/example_laptops/download" \
  -H "Authorization: Bearer $STRING_FEED_BUILDER_KEY" \
  --data-urlencode "path=101/part-0.json.gz" \
  -o part-0.json.gz

The response is the file's bytes, with Content-Type and Content-Disposition: attachment. Retry if your HTTP client reports an incomplete download. Fetch a backlog a few files at a time; on 429, wait for Retry-After before retrying.

Rules and limits

• Signed links expire. Fetch default exports before expires_at, and list again for fresh links rather than storing them. Anyone holding a signed url can download the file until it expires. Do not log or share it.
• Page until truncated is false. Files come back in path order, not by date. A page can hold fewer than page_size files, or none, while truncated is still true. Keep following next_page_token. A listing is not a snapshot: new files may arrive while you page through it.
• Exports are kept for 30 days. Download files within that window if you need to keep them longer.
• An empty final page means no more matching files remain. If it is also the first page, no retained files matched. Collected files may have expired or fall outside your time filters.

Errors

Every other status has the meaning on Errors.