Skip to main content

Artifacts and Files

Some turns produce files as well as an answer: a report, a dashboard, a slide deck, or a spreadsheet. These are artifacts. Every artifact is also a file in your SuperAnalyst workspace, and its id works on both the artifact and file endpoints.

The samples continue from the Quick Start.

List a session's artifacts​

GET /sessions/{session_id}/artifacts returns one page of artifacts. Keep paging with cursor until next_cursor is null.

{
"object": "list",
"session_id": "…",
"data": [
{
"id": "…",
"object": "artifact",
"superanalyst_id": "default",
"session_id": "…",
"file_id": "…",
"name": "semiconductor_comps.xlsx",
"type": "spreadsheet",
"mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"updated_at": "2026-11-16T14:04:30Z"
}
],
"next_cursor": null
}
  • type is dashboard, report, slide, spreadsheet, or other. It can be missing for new kinds of file.
  • mime_type comes from the file extension.
  • Lists have no size. GET /artifacts/{artifact_id} returns the same fields plus size_bytes.
  • A session that produced no files returns an empty list.

Download an artifact​

GET /artifacts/{artifact_id}/content returns the file inside JSON. Read the delivery field:

  • inline with encoding: "utf-8": a text file, in content.
  • inline with encoding: "base64": a binary file, in content_base64. Decode it.
  • too_large: the file is over the download size limit (see Timeouts and limits) and can't be downloaded through the API yet.

A file that is too large still returns 200, so check delivery rather than the status code.

{
"id": "…",
"object": "artifact.content",
"delivery": "inline",
"encoding": "base64",
"content_base64": "UEsDBBQABgAI…"
}

Save every artifact from a session​

The samples skip files that can't be read or are too large. They number the files so two with the same name don't overwrite each other, and keep only the base name so nothing is written outside the folder.

import base64
import os
from urllib.parse import quote

import requests


def list_artifacts(session_url):
params = {"limit": 100}
while True:
page = api.get(f"{session_url}/artifacts", params=params).json()
yield from page["data"]
if not page["next_cursor"]:
return
params["cursor"] = page["next_cursor"]


os.makedirs("artifacts", exist_ok=True)
for number, artifact in enumerate(list_artifacts(session_url), start=1):
name = os.path.basename(artifact["name"])
try:
file = api.get(f"{API_URL}/artifacts/{quote(artifact['id'], safe='')}/content").json()
except requests.HTTPError as error:
print(f"Skipped {name}: HTTP {error.response.status_code}")
continue
if file["delivery"] != "inline":
print(f"Skipped {name}: {file['error']['code']}")
continue
if file["encoding"] == "base64":
data = base64.b64decode(file["content_base64"])
else:
data = file["content"].encode("utf-8")
path = os.path.join("artifacts", f"{number:02d}-{name}")
with open(path, "wb") as f:
f.write(data)
print(f"Saved {path}")

Browse your workspace​

GET /files lists one folder of your workspace. Pass a folder's path to list inside it, and omit path for the root. It pages with cursor the same way.

{
"object": "list",
"path": "",
"data": [
{
"id": "…",
"object": "file",
"name": "reports",
"path": "reports",
"type": "directory",
"mime_type": null,
"size_bytes": null,
"updated_at": "2026-11-16T14:04:30Z"
}
],
"next_cursor": null
}
  • GET /files/{file_id} returns one entry. GET /files/{file_id}/content downloads it with the same delivery rules as artifacts. A folder's content returns 400.
  • Listing goes one level at a time, with no search or total count.
  • If files change while you page, entries can shift between pages. A cursor that is too old is ignored, and the listing starts again from the first page.
  • size_bytes can be null for some files.
  • In a large folder, a file past the first page of that folder can return 404 on GET /files/{file_id}.
  • A few entries can be listed but not read. They return 502 UPSTREAM_ERROR, and retrying usually fails the same way, so skip them.