Datasets

A dataset is a list of JSON items, usually the results of a run: one item per product, post, review or page. Items are returned as the actor stored them.

View and export in the Console

Open a run's Output tab, or Storage → Datasets and a dataset.

• The table keeps its columns across pages; sort a column or use Search this page (it filters the items shown, not the whole dataset). Hide fields starting with # hides technical fields.
• If the actor defines dataset views, pick one under Dataset view for a ready-made table.
• Export downloads the dataset as JSON, CSV, JSON Lines, Excel (XLSX) or HTML. Excel and HTML are limited to 20,000 items.

Read items with the API

First 100 items as JSON

curl -s "https://lantfly.com/api/v3/datasets/$DATASET_ID/items?limit=100" \
  -H "Authorization: Bearer $LANTFLY_TOKEN"

The JSON answer is { "data": [items], "meta": { "total", "offset", "limit", "count", "desc" } }.

Formats

Set format:

format	Output	Most items per request
json (default)	{ data, meta }	250,000
jsonl	One JSON item per line	250,000
csv	CSV with a header row	250,000
xlsx	Excel workbook	20,000
html	HTML table	20,000
xml	XML document	20,000
rss	RSS feed	20,000

json, jsonl and csv are streamed, so large exports start at once. A limit above the maximum is lowered to it without an error. Tabular formats (CSV, Excel, HTML) turn nested values into parent/child columns. Cells that would start a spreadsheet formula are written as plain text.

Export as CSV

curl -s "https://lantfly.com/api/v3/datasets/$DATASET_ID/items?format=csv&bom=1" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" -o items.csv

Parameters

Parameter	Meaning
offset, limit	Paging: skip offset items, return at most limit
desc	1 returns the newest items first
fields	Comma-separated fields to keep
omit	Comma-separated fields to drop
unwind	Array field(s) to spread into one item per element
flatten	Nested object field(s) to turn into parent.child keys
clean	1 drops fields whose names start with #, then items left empty
skip_hidden	Same as clean
view	A dataset view defined by the actor (its fields and transformations); parameters you send explicitly win
delimiter, bom, skip_header_row	CSV options: separator, a UTF-8 byte order mark for Excel, no header row
xml_root, xml_row	XML element names for the document and each item

An unknown view answers 400 invalid_parameter.

Pagination

Every answer also carries the headers X-Lantfly-Pagination-Total, -Offset, -Limit, -Count and -Desc. Page through a large dataset by raising offset by limit until you have total items. For streamed formats, Count is the number of stored items in the page, before clean or unwind. See Pagination.

Read every item, 1,000 at a time

import os
import requests

API = "https://lantfly.com/api/v3"
headers = {"Authorization": f"Bearer {os.environ['LANTFLY_TOKEN']}"}
dataset_id = os.environ["DATASET_ID"]

offset, items = 0, []
while True:
    page = requests.get(
        f"{API}/datasets/{dataset_id}/items",
        headers=headers,
        params={"offset": offset, "limit": 1000},
        timeout=60,
    ).json()
    items += page["data"]
    offset += page["meta"]["count"]
    if page["meta"]["count"] == 0 or offset >= page["meta"]["total"]:
        break

Add items

POST /api/v3/datasets/:dataset/items stores one item (an object) or a list of items. Actors usually do this through the SDK (Actor.pushData).

Push two items

curl -s -X POST "https://lantfly.com/api/v3/datasets/my-results/items" \
  -H "Authorization: Bearer $LANTFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{ "title": "First" }, { "title": "Second" }]'

Share a public link

Each dataset has an items_public_url: a signed link to its items that anyone can open without a token, in any of the formats above (add &format=csv and so on). Use it to give results to a tool or a person who has no Lantfly account.

• Public links expire after 7 days by default. Fetch the dataset again (GET /api/v3/datasets/:dataset) to get a fresh link.
• A wrong or expired signature answers 403 invalid_signature.

To withdraw every link already handed out, rotate the dataset's signing key:

Invalidate all public links of a dataset

curl -s -X POST "https://lantfly.com/api/v3/datasets/$DATASET_ID/rotate-signing-key" \
  -H "Authorization: Bearer $LANTFLY_TOKEN"

The answer is the dataset with its new items_public_url. A run token cannot call this.

See Signed links for how signatures work.

General access

If you set Settings → Login & privacy → General resource access to let anyone with the ID read, a dataset's items can be read with just its ID, without a token or a signature. Writes still need a token. See Storage.

Rename and delete

Request	What it does
PATCH /api/v3/datasets/:dataset { "name": "…" }	Name or rename it (named datasets are kept past retention); null makes it unnamed
DELETE /api/v3/datasets/:dataset	Delete it and its items