Skip to main content
import upnext

@worker.task
async def generate_report(report_type: str) -> dict:
    data = {"type": report_type, "rows": 42}

    await upnext.create_artifact(
        name="report.json",
        data=data,
        artifact_type=upnext.ArtifactType.JSON,
    )

    return data
Artifacts are named outputs attached to a job. Use them to store results, reports, images, or any file that you want to retrieve later from the API or dashboard.

Create an artifact

Call upnext.create_artifact() from inside a task:
await upnext.create_artifact(
    name="output.json",
    data={"key": "value"},
)
For sync tasks, use the sync variant:
upnext.create_artifact_sync(
    name="output.json",
    data={"key": "value"},
)

Parameters

ParameterTypeDefaultDescription
namestrrequiredArtifact filename (e.g. "report.json")
datastr | dict | listrequiredArtifact content (see types below)
artifact_typeArtifactTypeJSONType of artifact

Artifact types

TypeData formatUse case
ArtifactType.JSONdict or listStructured data, API responses
ArtifactType.TEXTstrPlain text, logs
ArtifactType.PNGstr (base64)PNG images
ArtifactType.JPEGstr (base64)JPEG images
ArtifactType.WEBPstr (base64)WebP images
ArtifactType.GIFstr (base64)GIF images
ArtifactType.SVGstr (base64)SVG images
ArtifactType.PDFstr (base64)PDF documents
ArtifactType.CSVstr (base64)CSV files
ArtifactType.XMLstr (base64)XML documents
ArtifactType.HTMLstr (base64)HTML documents
ArtifactType.BINARYstr (base64)Any binary file

Examples

JSON artifact

await upnext.create_artifact(
    name="results.json",
    data={"users": 150, "errors": 3},
)

Text artifact

await upnext.create_artifact(
    name="log.txt",
    data="Processing completed successfully.\n3 warnings.",
    artifact_type=upnext.ArtifactType.TEXT,
)

Image artifact

Binary artifacts (images, PDFs, etc.) must be base64-encoded:
import base64

with open("chart.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("ascii")

await upnext.create_artifact(
    name="chart.png",
    data=encoded,
    artifact_type=upnext.ArtifactType.PNG,
)

Viewing artifacts

Artifacts are visible in the dashboard’s Artifacts page and on individual job detail views. You can also retrieve them via the server’s REST API.

Storage backends

By default, artifacts are stored on the local filesystem. For production, you can configure S3 storage:
UPNEXT_ARTIFACT_STORAGE_BACKEND=s3
See the Configuration reference for all storage-related environment variables.