Get an artifact

Returns an artifact's metadata with a fresh signed URL (valid for 24 hours). The URL needs no credentials and is safe to embed: it works for anyone who has it until `url_expires_at`, and the bytes are always served with `Content-Security-Policy: sandbox` (URL format: `renderGetArtifactContent`).

GET /v1/render/artifacts/{artifact_id}

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Path Parameters

artifact_id string required path

The artifact ID (`art_…`).

Example: "art_01m5t41x77fg4pdnm2ryq73wgs"

Responses

200 The artifact.

application/json

id string REQUIRED

object string REQUIRED

Enum: artifact

kind string REQUIRED

Enum: image, mp4, gif, poster, vtt, srt

content_type string REQUIRED

bytes integer

width integer

height integer

duration_ms integer

url string (uri)

Signed URL on `usercontent.b3os.org`, `https://usercontent.b3os.org/a/<id in host-safe form>/<name>?node=&exp=&sig=`: an Ed25519 signature by the node's key over the method, path and expiry (`renderGetArtifactContent`), no cookies. It works as soon as the artifact is reported, while the upload to storage is still finishing.

url_expires_at string (date-time)

created_at string (date-time)

expires_at string (date-time)

When the artifact is deleted.

400 The request failed validation (`invalid_request`, `invalid_url`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

401 Missing, malformed, expired or revoked credentials (`unauthorized`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

403 Authenticated but not allowed (`forbidden`, `egress_denied`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

404 No such artifact in this project (`artifact_not_found`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

410 The artifact was deleted at the end of its retention period (`artifact_expired`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

500 Something failed inside B3OS (`internal`). Retry with backoff.

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`).

application/problem+json

type string (uri) REQUIRED

`https://docs.beta.b3os.org/errors#<code>`.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (`req_…`) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (`invalid_request` and the other codes that list `errors`).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).

required_scope string

The scope that was missing (`forbidden` with `reason: scope`).

retry_after_s integer

Same value as the `Retry-After` header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.

id string REQUIRED

Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as `sandbox_not_running`.

upstream_status integer

The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).

step string

The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).

pack_error object

The error a pack's error mapping chose (`upstream_error` from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

curl -X GET 'https://beta-api.b3os.org/v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs' \  -H 'Authorization: Bearer YOUR_API_TOKEN'

const response = await fetch('https://beta-api.b3os.org/v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);

import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/render/artifacts/art_01m5t41x77fg4pdnm2ryq73wgs', headers=headers)print(response.json())

200 Response

{  "id": "art_01m5t3nhzatn0b868d7pf7fh82",  "object": "artifact",  "kind": "poster",  "content_type": "image/jpeg",  "bytes": 98211,  "width": 1920,  "height": 1080,  "url": "https://usercontent.b3os.org/a/art-01m5t3nhzatn0b868d7pf7fh82/poster.jpg?node=n1&exp=1793040604&sig=ANijY83svvEUxb4X2Zo7fu8iEpsYJFSH_nPx7MpqcaW_EteYq9LYyOaOJLge5-pAhk1iNx60d6rBaBnJftlABw",  "url_expires_at": "2026-10-26T18:50:04.000Z",  "created_at": "2026-10-25T18:50:03.900Z",  "expires_at": "2026-11-01T18:50:03.900Z"}

400 Response

{  "type": "https://docs.beta.b3os.org/errors#invalid_request",  "title": "Invalid request",  "status": 400,  "code": "invalid_request",  "detail": "1 field failed validation",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "errors": [    {      "pointer": "/url",      "detail": "must be an absolute http or https URL"    }  ]}

401 Response

{  "type": "https://docs.beta.b3os.org/errors#unauthorized",  "title": "Unauthorized",  "status": 401,  "code": "unauthorized",  "detail": "API key checksum does not match; check that the whole key was copied",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "reason": "malformed"}

403 Response

{  "type": "https://docs.beta.b3os.org/errors#forbidden",  "title": "Forbidden",  "status": 403,  "code": "forbidden",  "detail": "This key lacks the scope sandboxes:write",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "reason": "scope",  "required_scope": "sandboxes:write"}

404 Response

{  "type": "https://docs.beta.b3os.org/errors#artifact_not_found",  "title": "Artifact not found",  "status": 404,  "code": "artifact_not_found",  "detail": "No artifact art_01m5t41x77fg4pdnm2ryq73wgs in this project",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

410 Response

{  "type": "https://docs.beta.b3os.org/errors#artifact_expired",  "title": "Artifact expired",  "status": 410,  "code": "artifact_expired",  "detail": "art_01m5t41x77fg4pdnm2ryq73wgs expired on 2026-11-01T18:40:00Z",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

429 Response

{  "type": "https://docs.beta.b3os.org/errors#rate_limited",  "title": "Rate limited",  "status": 429,  "code": "rate_limited",  "detail": "60 scrapes per minute allowed; retry in 12 seconds",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "retry_after_s": 12,  "limit": {    "id": "vision.scrape.rpm",    "limit": 60,    "unit": "requests",    "window_s": 60,    "current": 60  }}

500 Response

{  "type": "https://docs.beta.b3os.org/errors#internal",  "title": "Internal error",  "status": 500,  "code": "internal",  "detail": "internal error",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

503 Response

{  "type": "https://docs.beta.b3os.org/errors#node_unavailable",  "title": "Node unavailable",  "status": 503,  "code": "node_unavailable",  "detail": "Node n1 is not reachable; retry in 5 seconds",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "retry_after_s": 5}

GET /v1/render/artifacts/{artifact_id}

Base URL

Bearer Token

Path Parameters

artifact_id string required

Response

Was this page helpful?

Previous Get a video's timeline

Next Download an artifact's bytes