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
}
typeisdashboard,report,slide,spreadsheet, orother. It can be missing for new kinds of file.mime_typecomes from the file extension.- Lists have no size.
GET /artifacts/{artifact_id}returns the same fields plussize_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:
inlinewithencoding: "utf-8": a text file, incontent.inlinewithencoding: "base64": a binary file, incontent_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.
- Python
- JavaScript
- cURL
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}")
import {mkdir, writeFile} from 'node:fs/promises'
import path from 'node:path'
async function* listArtifacts(sessionPath) {
let cursor = null
do {
const query = new URLSearchParams({limit: 100, ...(cursor && {cursor})})
const page = await api(`${sessionPath}/artifacts?${query}`)
yield* page.data
cursor = page.next_cursor
} while (cursor)
}
await mkdir('artifacts', {recursive: true})
let number = 0
for await (const artifact of listArtifacts(sessionPath)) {
number += 1
const name = path.basename(artifact.name)
let file
try {
file = await api(`/artifacts/${encodeURIComponent(artifact.id)}/content`)
} catch (error) {
console.log(`Skipped ${name}: ${error.message}`)
continue
}
if (file.delivery !== 'inline') {
console.log(`Skipped ${name}: ${file.error.code}`)
continue
}
const data =
file.encoding === 'base64'
? Buffer.from(file.content_base64, 'base64')
: Buffer.from(file.content)
const target = path.join('artifacts', `${String(number).padStart(2, '0')}-${name}`)
await writeFile(target, data)
console.log(`Saved ${target}`)
}
curl -sS "$SESSION_URL/artifacts?limit=100" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq '.data[] | {id, name, type}'
# Download one binary artifact, using an id from the list.
curl -sS "$API_URL/artifacts/<artifact id>/content" -H "Authorization: Bearer $ACCESS_TOKEN" \
| jq -r '.content_base64 // error("Not inline binary content. Check delivery and encoding.")' \
| base64 --decode > semiconductor_comps.xlsx
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}/contentdownloads it with the samedeliveryrules as artifacts. A folder's content returns400.- 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
cursorthat is too old is ignored, and the listing starts again from the first page. size_bytescan benullfor some files.- In a large folder, a file past the first page of that folder can return
404onGET /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.