diff --git a/docs/reference/advanced/artifacts.md b/docs/reference/advanced/artifacts.md
new file mode 100644
index 000000000..9537b538c
--- /dev/null
+++ b/docs/reference/advanced/artifacts.md
@@ -0,0 +1,88 @@
+# Artifacts
+
+Artifacts let you attach a **binary blob** — an image, audio clip, PDF, or a large JSON
+payload — to a span. The blob is stored separately from your telemetry, so it is not
+subject to span attribute size limits and does not bloat your traces. The span itself
+carries only a small reference; Logfire uploads the blob out of band.
+
+## Logging an artifact
+
+Wrap your data in `logfire.Artifact` and pass it as a span or log attribute:
+
+```python skip="true"
+import logfire
+
+logfire.configure()
+
+with open('chart.png', 'rb') as f:
+    image_bytes = f.read()
+
+logfire.info('chart generated', chart=logfire.Artifact(image_bytes, content_type='image/png'))
+```
+
+The `chart` argument renders as an image preview on the trace in the Logfire UI, with a
+download link — not as a wall of base64.
+
+### From a file or a file handle
+
+`Artifact.from_file` reads a path lazily (no need to load the bytes yourself), and
+`Artifact.from_file_handle` accepts any open binary handle, including temporary files:
+
+```python skip="true"
+import logfire
+
+logfire.configure()
+
+# From a path — the content type is guessed from the extension.
+logfire.info('report ready', report=logfire.Artifact.from_file('report.pdf'))
+
+# From an open binary handle.
+with open('clip.mp3', 'rb') as handle:
+    logfire.info('audio processed', clip=logfire.Artifact.from_file_handle(handle))
+```
+
+## When the upload happens
+
+Each artifact chooses when its bytes are uploaded, via the `upload` argument:
+
+- **`background`** (the default) — the upload is handed to a background thread and the
+  logging call never blocks. If uploads cannot keep up, queued artifacts are dropped
+  with a warning rather than stalling your program.
+- **`sync`** — the upload runs inline; the logging call returns only once the blob is
+  stored. Use this when you need delivery guaranteed, or when you want to free the
+  source bytes/file immediately afterwards.
+
+```python skip="true"
+import logfire
+
+logfire.configure()
+
+# Block until this artifact is uploaded.
+logfire.info('critical input', data=logfire.Artifact(payload, upload='sync'))
+```
+
+## How it works
+
+Artifacts are **content-addressed**: an artifact's identity is the sha256 of its bytes.
+The same blob logged repeatedly — within a project — is uploaded and stored only once.
+The reference embedded in the span looks like:
+
+```json
+{
+  "type": "logfire.artifact",
+  "sha256": "9f86d0818...",
+  "filename": "chart.png",
+  "content_type": "image/png",
+  "size_bytes": 28421
+}
+```
+
+The blob never travels through the telemetry pipeline. On SaaS the SDK uploads it
+directly to object storage via a signed URL; self-hosted deployments route it through
+the Logfire backend.
+
+## Viewing artifacts
+
+Open a span in the Logfire UI: any artifact-valued argument renders inline — images,
+audio, video, and PDFs as previews, everything else as a download link — alongside its
+filename, content type, and size.
diff --git a/logfire-api/logfire_api/__init__.py b/logfire-api/logfire_api/__init__.py
index 7931b4374..b581d4aee 100644
--- a/logfire-api/logfire_api/__init__.py
+++ b/logfire-api/logfire_api/__init__.py
@@ -2,11 +2,11 @@
 
 import importlib
 import sys
+from collections.abc import Sequence
 from contextlib import contextmanager, nullcontext
-from typing import Any, ContextManager, Literal, TYPE_CHECKING, Sequence
+from typing import TYPE_CHECKING, Any, ContextManager, Literal
 from unittest.mock import MagicMock
 
-
 try:
     logfire_module = importlib.import_module('logfire')
     sys.modules[__name__] = logfire_module
@@ -85,7 +85,7 @@ def end_time(self):
             def parent(self):
                 return None
 
-            def set_attribute(self, key: str, value: Any) -> None: ... # pragma: no cover
+            def set_attribute(self, key: str, value: Any) -> None: ...  # pragma: no cover
 
         class Logfire:
             def __getattr__(self, attr):
@@ -208,7 +208,6 @@ def url_from_eval(self, *args, **kwargs) -> str | None: ...
 
             def shutdown(self, *args, **kwargs) -> None: ...
 
-
         DEFAULT_LOGFIRE_INSTANCE = Logfire()
         span = DEFAULT_LOGFIRE_INSTANCE.span
         log = DEFAULT_LOGFIRE_INSTANCE.log
@@ -293,7 +292,6 @@ def __init__(self, *args, **kwargs) -> None: ...
         class MetricsOptions:
             def __init__(self, *args, **kwargs) -> None: ...
 
-
         class PydanticPlugin:
             def __init__(self, *args, **kwargs) -> None: ...
 
@@ -309,6 +307,19 @@ def __init__(self, *args, **kwargs) -> None: ...
         class LogfireLoggingHandler:
             def __init__(self, *args, **kwargs) -> None: ...
 
+        UploadMode = Literal['sync', 'background']
+
+        class Artifact:
+            def __init__(self, *args, **kwargs) -> None: ...
+
+            @classmethod
+            def from_file(cls, *args, **kwargs) -> Artifact:
+                return cls()
+
+            @classmethod
+            def from_file_handle(cls, *args, **kwargs) -> Artifact:
+                return cls()
+
         def logfire_info() -> str:
             """Show versions of logfire, OS and related packages."""
             return 'logfire_info() is not implement by logfire-api'
diff --git a/logfire-api/logfire_api/__init__.pyi b/logfire-api/logfire_api/__init__.pyi
index e73789536..ce561a653 100644
--- a/logfire-api/logfire_api/__init__.pyi
+++ b/logfire-api/logfire_api/__init__.pyi
@@ -1,22 +1,34 @@
+from typing import Any
+
+from logfire.propagate import attach_context as attach_context, get_context as get_context
+from logfire.sampling import SamplingOptions as SamplingOptions
+
 from . import variables as variables
+from ._internal.artifacts import Artifact as Artifact, UploadMode as UploadMode
 from ._internal.auto_trace import AutoTraceModule as AutoTraceModule
 from ._internal.auto_trace.rewrite_ast import no_auto_trace as no_auto_trace
 from ._internal.baggage import get_baggage as get_baggage, set_baggage as set_baggage
 from ._internal.cli import logfire_info as logfire_info
-from ._internal.config import AdvancedOptions as AdvancedOptions, CodeSource as CodeSource, ConsoleOptions as ConsoleOptions, LocalVariablesOptions as LocalVariablesOptions, MetricsOptions as MetricsOptions, PydanticPlugin as PydanticPlugin, VariablesOptions as VariablesOptions, configure as configure
+from ._internal.config import (
+    AdvancedOptions as AdvancedOptions,
+    CodeSource as CodeSource,
+    ConsoleOptions as ConsoleOptions,
+    LocalVariablesOptions as LocalVariablesOptions,
+    MetricsOptions as MetricsOptions,
+    PydanticPlugin as PydanticPlugin,
+    VariablesOptions as VariablesOptions,
+    configure as configure,
+)
 from ._internal.constants import LevelName as LevelName
 from ._internal.main import Logfire as Logfire, LogfireSpan as LogfireSpan
-from ._internal.scrubbing import ScrubMatch as ScrubMatch, ScrubbingOptions as ScrubbingOptions
+from ._internal.scrubbing import ScrubbingOptions as ScrubbingOptions, ScrubMatch as ScrubMatch
 from ._internal.stack_info import add_non_user_code_prefix as add_non_user_code_prefix
 from ._internal.utils import suppress_instrumentation as suppress_instrumentation
 from .integrations.logging import LogfireLoggingHandler as LogfireLoggingHandler
 from .integrations.structlog import LogfireProcessor as StructlogProcessor
 from .version import VERSION as VERSION
-from logfire.propagate import attach_context as attach_context, get_context as get_context
-from logfire.sampling import SamplingOptions as SamplingOptions
-from typing import Any
 
-__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'warning', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_asgi', 'instrument_wsgi', 'instrument_pydantic', 'instrument_pydantic_ai', 'instrument_fastapi', 'instrument_openai', 'instrument_openai_agents', 'instrument_anthropic', 'instrument_google_genai', 'instrument_litellm', 'instrument_dspy', 'instrument_print', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_aiohttp_server', 'instrument_sqlalchemy', 'instrument_sqlite3', 'instrument_aws_lambda', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_surrealdb', 'instrument_system_metrics', 'instrument_mcp', 'instrument_claude_agent_sdk', 'AutoTraceModule', 'with_tags', 'with_settings', 'suppress_scopes', 'shutdown', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'add_non_user_code_prefix', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions', 'VariablesOptions', 'LocalVariablesOptions', 'variables', 'var', 'variables_clear', 'variables_get', 'variables_push', 'variables_push_types', 'variables_validate', 'variables_push_config', 'variables_pull_config', 'variables_build_config', 'logfire_info', 'get_baggage', 'set_baggage', 'get_context', 'attach_context', 'url_from_eval']
+__all__ = ['Logfire', 'LogfireSpan', 'LevelName', 'AdvancedOptions', 'ConsoleOptions', 'CodeSource', 'PydanticPlugin', 'configure', 'span', 'instrument', 'log', 'trace', 'debug', 'notice', 'info', 'warn', 'warning', 'error', 'exception', 'fatal', 'force_flush', 'log_slow_async_callbacks', 'install_auto_tracing', 'instrument_asgi', 'instrument_wsgi', 'instrument_pydantic', 'instrument_pydantic_ai', 'instrument_fastapi', 'instrument_openai', 'instrument_openai_agents', 'instrument_anthropic', 'instrument_google_genai', 'instrument_litellm', 'instrument_dspy', 'instrument_print', 'instrument_asyncpg', 'instrument_httpx', 'instrument_celery', 'instrument_requests', 'instrument_psycopg', 'instrument_django', 'instrument_flask', 'instrument_starlette', 'instrument_aiohttp_client', 'instrument_aiohttp_server', 'instrument_sqlalchemy', 'instrument_sqlite3', 'instrument_aws_lambda', 'instrument_redis', 'instrument_pymongo', 'instrument_mysql', 'instrument_surrealdb', 'instrument_system_metrics', 'instrument_mcp', 'instrument_claude_agent_sdk', 'AutoTraceModule', 'with_tags', 'with_settings', 'suppress_scopes', 'shutdown', 'no_auto_trace', 'ScrubMatch', 'ScrubbingOptions', 'VERSION', 'add_non_user_code_prefix', 'suppress_instrumentation', 'StructlogProcessor', 'LogfireLoggingHandler', 'loguru_handler', 'SamplingOptions', 'MetricsOptions', 'VariablesOptions', 'LocalVariablesOptions', 'variables', 'var', 'variables_clear', 'variables_get', 'variables_push', 'variables_push_types', 'variables_validate', 'variables_push_config', 'variables_pull_config', 'variables_build_config', 'logfire_info', 'get_baggage', 'set_baggage', 'get_context', 'attach_context', 'url_from_eval', 'Artifact', 'UploadMode']
 
 DEFAULT_LOGFIRE_INSTANCE = Logfire()
 span = DEFAULT_LOGFIRE_INSTANCE.span
diff --git a/logfire-api/logfire_api/_internal/artifacts.pyi b/logfire-api/logfire_api/_internal/artifacts.pyi
new file mode 100644
index 000000000..409e083b7
--- /dev/null
+++ b/logfire-api/logfire_api/_internal/artifacts.pyi
@@ -0,0 +1,111 @@
+import os
+from abc import ABC, abstractmethod
+from typing import IO, Any
+
+from _typeshed import Incomplete
+
+__all__ = ['Artifact', 'UploadMode']
+
+UploadMode: Incomplete
+
+class ArtifactSource(ABC):
+    """A source of artifact bytes — normalises bytes, files, and handles to one surface.
+
+    Deliberately small so that streaming sources can be added later as a new subclass
+    without touching `Artifact`, the upload handshake, or the backend.
+    """
+    @abstractmethod
+    def digest(self) -> tuple[str, int]:
+        """Return `(sha256_hex, size_bytes)` for the content."""
+    @abstractmethod
+    def read(self) -> bytes:
+        """Return the full content as bytes, for upload."""
+
+class _BytesSource(ArtifactSource):
+    """An in-memory blob."""
+    def __init__(self, data: bytes) -> None: ...
+    def digest(self) -> tuple[str, int]: ...
+    def read(self) -> bytes: ...
+
+class _PathSource(ArtifactSource):
+    """A file on disk.
+
+    Hashed and uploaded by reading the path, so a `background` upload of a file path
+    holds no bytes in memory.
+    """
+    def __init__(self, path: str | os.PathLike[str]) -> None: ...
+    def digest(self) -> tuple[str, int]: ...
+    def read(self) -> bytes: ...
+
+class Artifact:
+    """A binary blob to attach to a span — an image, audio clip, PDF, large JSON, etc.
+
+    Pass an `Artifact` as a span or log attribute value. Logfire uploads the blob to
+    object storage out of band and embeds a small reference in the span.
+
+    Examples:
+        ```python
+        import logfire
+
+        logfire.configure()
+
+        # From a file path.
+        logfire.info('chart generated', chart=logfire.Artifact.from_file('chart.png'))
+
+        # From in-memory bytes.
+        logfire.info('thumbnail', image=logfire.Artifact(png_bytes, content_type='image/png'))
+
+        # From an open binary handle (including temporary / spooled files).
+        with open('report.pdf', 'rb') as handle:
+            logfire.info('report', report=logfire.Artifact.from_file_handle(handle))
+        ```
+    """
+    def __init__(self, data: bytes, *, filename: str | None = None, content_type: str | None = None, upload: UploadMode = 'background') -> None:
+        """Create an artifact from in-memory bytes.
+
+        Args:
+            data: The blob bytes.
+            filename: Optional original filename, shown in the UI and used to guess the
+                content type.
+            content_type: MIME type of the blob. Guessed from `filename` when omitted,
+                falling back to `application/octet-stream`.
+            upload: When to upload the blob — see [`UploadMode`][logfire.UploadMode].
+                Defaults to `background`.
+        """
+    @classmethod
+    def from_file(cls, path: str | os.PathLike[str], *, filename: str | None = None, content_type: str | None = None, upload: UploadMode = 'background') -> Artifact:
+        """Create an artifact from a file path.
+
+        The file is read once to hash it and again to upload it, so a `background`
+        upload of a file path holds no bytes in memory.
+
+        Args:
+            path: Path to the file.
+            filename: Original filename to record. Defaults to the basename of `path`.
+            content_type: MIME type. Guessed from the path/filename when omitted.
+            upload: When to upload the blob — see [`UploadMode`][logfire.UploadMode].
+        """
+    @classmethod
+    def from_file_handle(cls, handle: IO[bytes], *, filename: str | None = None, content_type: str | None = None, upload: UploadMode = 'background') -> Artifact:
+        """Create an artifact from an open binary file handle.
+
+        Works with any binary handle, including `tempfile.SpooledTemporaryFile` and
+        `tempfile.NamedTemporaryFile`. The handle is read in full immediately, so the
+        caller may close it as soon as this returns.
+
+        Args:
+            handle: An open binary (`'rb'`) file-like object.
+            filename: Original filename to record. Defaults to the handle's `name`.
+            content_type: MIME type. Guessed from the filename when omitted.
+            upload: When to upload the blob — see [`UploadMode`][logfire.UploadMode].
+        """
+    @property
+    def sha256(self) -> str:
+        """The hex sha256 of the blob — its content-addressed identity."""
+    @property
+    def size_bytes(self) -> int:
+        """The size of the blob in bytes."""
+    def read(self) -> bytes:
+        """Read the full blob into memory (used by the uploader)."""
+    def reference(self) -> dict[str, Any]:
+        """The reference object embedded into the span attribute in place of the blob."""
diff --git a/logfire-api/logfire_api/_internal/config.pyi b/logfire-api/logfire_api/_internal/config.pyi
index 7cfc1f567..c7218a0ed 100644
--- a/logfire-api/logfire_api/_internal/config.pyi
+++ b/logfire-api/logfire_api/_internal/config.pyi
@@ -1,31 +1,19 @@
 import dataclasses
-import requests
-from ..propagate import NoExtractTraceContextPropagator as NoExtractTraceContextPropagator, WarnOnExtractTraceContextPropagator as WarnOnExtractTraceContextPropagator
-from ..types import ExceptionCallback as ExceptionCallback
-from .client import InvalidProjectName as InvalidProjectName, LogfireClient as LogfireClient, ProjectAlreadyExists as ProjectAlreadyExists
-from .config_params import ParamManager as ParamManager, PydanticPluginRecordValues as PydanticPluginRecordValues, normalize_token as normalize_token
-from .constants import ATTRIBUTES_CONFIG as ATTRIBUTES_CONFIG, ATTRIBUTES_PACKAGE_VERSIONS as ATTRIBUTES_PACKAGE_VERSIONS, LEVEL_NUMBERS as LEVEL_NUMBERS, LevelName as LevelName, RESOURCE_ATTRIBUTES_CODE_ROOT_PATH as RESOURCE_ATTRIBUTES_CODE_ROOT_PATH, RESOURCE_ATTRIBUTES_CODE_WORK_DIR as RESOURCE_ATTRIBUTES_CODE_WORK_DIR, RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME as RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME, RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION, RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL, RESOURCE_ATTRIBUTES_VERSION as RESOURCE_ATTRIBUTES_VERSION
-from .exporters.console import ConsoleColorsValues as ConsoleColorsValues, ConsoleLogExporter as ConsoleLogExporter, IndentedConsoleSpanExporter as IndentedConsoleSpanExporter, ShowParentsConsoleSpanExporter as ShowParentsConsoleSpanExporter, SimpleConsoleSpanExporter as SimpleConsoleSpanExporter
-from .exporters.dynamic_batch import DynamicBatchSpanProcessor as DynamicBatchSpanProcessor
-from .exporters.logs import CheckSuppressInstrumentationLogProcessorWrapper as CheckSuppressInstrumentationLogProcessorWrapper, MainLogProcessorWrapper as MainLogProcessorWrapper
-from .exporters.otlp import BodySizeCheckingOTLPSpanExporter as BodySizeCheckingOTLPSpanExporter, OTLPExporterHttpSession as OTLPExporterHttpSession, QuietLogExporter as QuietLogExporter, QuietSpanExporter as QuietSpanExporter, RetryFewerSpansSpanExporter as RetryFewerSpansSpanExporter, cleanup_disk_retryers as cleanup_disk_retryers
-from .exporters.processor_wrapper import CheckSuppressInstrumentationProcessorWrapper as CheckSuppressInstrumentationProcessorWrapper, MainSpanProcessorWrapper as MainSpanProcessorWrapper
-from .exporters.quiet_metrics import QuietMetricExporter as QuietMetricExporter
-from .exporters.remove_pending import RemovePendingSpansExporter as RemovePendingSpansExporter
-from .exporters.test import TestExporter as TestExporter
-from .integrations.executors import instrument_executors as instrument_executors
-from .logs import ProxyLoggerProvider as ProxyLoggerProvider
-from .main import Logfire as Logfire
-from .metrics import ProxyMeterProvider as ProxyMeterProvider
-from .scrubbing import BaseScrubber as BaseScrubber, NOOP_SCRUBBER as NOOP_SCRUBBER, Scrubber as Scrubber, ScrubbingOptions as ScrubbingOptions
-from .server_response import ServerResponseCallback as ServerResponseCallback, install_logfire_response_hook as install_logfire_response_hook
-from .stack_info import warn_at_user_stacklevel as warn_at_user_stacklevel
-from .tracer import OPEN_SPANS as OPEN_SPANS, PendingSpanProcessor as PendingSpanProcessor, ProxyTracerProvider as ProxyTracerProvider
-from .utils import SeededRandomIdGenerator as SeededRandomIdGenerator, ensure_data_dir_exists as ensure_data_dir_exists, handle_internal_errors as handle_internal_errors, platform_is_emscripten as platform_is_emscripten, suppress_instrumentation as suppress_instrumentation
-from _typeshed import Incomplete
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from datetime import timedelta
+from pathlib import Path
+from typing import Any, ClassVar, Literal, TextIO, TypedDict
+
+import requests
+from _typeshed import Incomplete
+from opentelemetry.sdk._logs import LogRecordProcessor as LogRecordProcessor
+from opentelemetry.sdk.metrics.export import MetricReader as MetricReader
+from opentelemetry.sdk.metrics.view import View
+from opentelemetry.sdk.trace import SpanProcessor
+from opentelemetry.sdk.trace.id_generator import IdGenerator
+from typing_extensions import Self, Unpack
+
 from logfire._internal.auth import PYDANTIC_LOGFIRE_TOKEN_PATTERN as PYDANTIC_LOGFIRE_TOKEN_PATTERN, REGIONS as REGIONS
 from logfire._internal.baggage import DirectBaggageAttributesSpanProcessor as DirectBaggageAttributesSpanProcessor
 from logfire._internal.collect_system_info import collect_package_info as collect_package_info
@@ -33,16 +21,95 @@ from logfire.exceptions import LogfireConfigError as LogfireConfigError
 from logfire.sampling import SamplingOptions as SamplingOptions
 from logfire.sampling._tail_sampling import TailSamplingProcessor as TailSamplingProcessor
 from logfire.variables import VariablesConfig as VariablesConfig
-from logfire.variables.abstract import NoOpVariableProvider as NoOpVariableProvider, VariableProvider as VariableProvider
+from logfire.variables.abstract import (
+    NoOpVariableProvider as NoOpVariableProvider,
+    VariableProvider as VariableProvider,
+)
 from logfire.version import VERSION as VERSION
-from opentelemetry.sdk._logs import LogRecordProcessor as LogRecordProcessor
-from opentelemetry.sdk.metrics.export import MetricReader as MetricReader
-from opentelemetry.sdk.metrics.view import View
-from opentelemetry.sdk.trace import SpanProcessor
-from opentelemetry.sdk.trace.id_generator import IdGenerator
-from pathlib import Path
-from typing import Any, ClassVar, Literal, TextIO, TypedDict
-from typing_extensions import Self, Unpack
+
+from ..propagate import (
+    NoExtractTraceContextPropagator as NoExtractTraceContextPropagator,
+    WarnOnExtractTraceContextPropagator as WarnOnExtractTraceContextPropagator,
+)
+from ..types import ExceptionCallback as ExceptionCallback
+from .artifacts import Artifact as Artifact
+from .client import (
+    InvalidProjectName as InvalidProjectName,
+    LogfireClient as LogfireClient,
+    ProjectAlreadyExists as ProjectAlreadyExists,
+)
+from .config_params import (
+    ParamManager as ParamManager,
+    PydanticPluginRecordValues as PydanticPluginRecordValues,
+    normalize_token as normalize_token,
+)
+from .constants import (
+    ATTRIBUTES_CONFIG as ATTRIBUTES_CONFIG,
+    ATTRIBUTES_PACKAGE_VERSIONS as ATTRIBUTES_PACKAGE_VERSIONS,
+    LEVEL_NUMBERS as LEVEL_NUMBERS,
+    RESOURCE_ATTRIBUTES_CODE_ROOT_PATH as RESOURCE_ATTRIBUTES_CODE_ROOT_PATH,
+    RESOURCE_ATTRIBUTES_CODE_WORK_DIR as RESOURCE_ATTRIBUTES_CODE_WORK_DIR,
+    RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME as RESOURCE_ATTRIBUTES_DEPLOYMENT_ENVIRONMENT_NAME,
+    RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_REF_REVISION,
+    RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL as RESOURCE_ATTRIBUTES_VCS_REPOSITORY_URL,
+    RESOURCE_ATTRIBUTES_VERSION as RESOURCE_ATTRIBUTES_VERSION,
+    LevelName as LevelName,
+)
+from .exporters.artifact_uploader import ArtifactUploader as ArtifactUploader
+from .exporters.console import (
+    ConsoleColorsValues as ConsoleColorsValues,
+    ConsoleLogExporter as ConsoleLogExporter,
+    IndentedConsoleSpanExporter as IndentedConsoleSpanExporter,
+    ShowParentsConsoleSpanExporter as ShowParentsConsoleSpanExporter,
+    SimpleConsoleSpanExporter as SimpleConsoleSpanExporter,
+)
+from .exporters.dynamic_batch import DynamicBatchSpanProcessor as DynamicBatchSpanProcessor
+from .exporters.logs import (
+    CheckSuppressInstrumentationLogProcessorWrapper as CheckSuppressInstrumentationLogProcessorWrapper,
+    MainLogProcessorWrapper as MainLogProcessorWrapper,
+)
+from .exporters.otlp import (
+    BodySizeCheckingOTLPSpanExporter as BodySizeCheckingOTLPSpanExporter,
+    OTLPExporterHttpSession as OTLPExporterHttpSession,
+    QuietLogExporter as QuietLogExporter,
+    QuietSpanExporter as QuietSpanExporter,
+    RetryFewerSpansSpanExporter as RetryFewerSpansSpanExporter,
+    cleanup_disk_retryers as cleanup_disk_retryers,
+)
+from .exporters.processor_wrapper import (
+    CheckSuppressInstrumentationProcessorWrapper as CheckSuppressInstrumentationProcessorWrapper,
+    MainSpanProcessorWrapper as MainSpanProcessorWrapper,
+)
+from .exporters.quiet_metrics import QuietMetricExporter as QuietMetricExporter
+from .exporters.remove_pending import RemovePendingSpansExporter as RemovePendingSpansExporter
+from .exporters.test import TestExporter as TestExporter
+from .integrations.executors import instrument_executors as instrument_executors
+from .logs import ProxyLoggerProvider as ProxyLoggerProvider
+from .main import Logfire as Logfire
+from .metrics import ProxyMeterProvider as ProxyMeterProvider
+from .scrubbing import (
+    NOOP_SCRUBBER as NOOP_SCRUBBER,
+    BaseScrubber as BaseScrubber,
+    Scrubber as Scrubber,
+    ScrubbingOptions as ScrubbingOptions,
+)
+from .server_response import (
+    ServerResponseCallback as ServerResponseCallback,
+    install_logfire_response_hook as install_logfire_response_hook,
+)
+from .stack_info import warn_at_user_stacklevel as warn_at_user_stacklevel
+from .tracer import (
+    OPEN_SPANS as OPEN_SPANS,
+    PendingSpanProcessor as PendingSpanProcessor,
+    ProxyTracerProvider as ProxyTracerProvider,
+)
+from .utils import (
+    SeededRandomIdGenerator as SeededRandomIdGenerator,
+    ensure_data_dir_exists as ensure_data_dir_exists,
+    handle_internal_errors as handle_internal_errors,
+    platform_is_emscripten as platform_is_emscripten,
+    suppress_instrumentation as suppress_instrumentation,
+)
 
 CREDENTIALS_FILENAME: str
 COMMON_REQUEST_HEADERS: Incomplete
@@ -253,6 +320,12 @@ class LogfireConfig(_LogfireConfigData):
         Returns:
             Whether the flush of spans was successful.
         """
+    def submit_artifact(self, artifact: Artifact) -> None:
+        """Upload an artifact's blob out of band — inline (`sync`) or queued (`background`).
+
+        No-op when there is no configured token (and hence no uploader): the artifact
+        reference is still recorded on the span, but the blob cannot be uploaded.
+        """
     def get_tracer_provider(self) -> ProxyTracerProvider:
         """Get a tracer provider from this `LogfireConfig`.
 
diff --git a/logfire-api/logfire_api/_internal/exporters/artifact_uploader.pyi b/logfire-api/logfire_api/_internal/exporters/artifact_uploader.pyi
new file mode 100644
index 000000000..a85290d8b
--- /dev/null
+++ b/logfire-api/logfire_api/_internal/exporters/artifact_uploader.pyi
@@ -0,0 +1,26 @@
+from _typeshed import Incomplete
+
+from ..artifacts import Artifact as Artifact
+from ..utils import log_internal_error as log_internal_error
+
+DEFAULT_MAX_QUEUE_BYTES: Incomplete
+
+class ArtifactUploader:
+    """Uploads artifact blobs to the Logfire backend.
+
+    Owns a daemon worker thread for `background` artifacts; `sync` artifacts are uploaded
+    on the calling thread.
+    """
+    def __init__(self, *, base_url: str, token: str, max_queue_bytes: int = ...) -> None: ...
+    def submit(self, artifact: Artifact) -> None:
+        """Upload an artifact's blob — inline for `sync`, queued for `background`.
+
+        A `background` submit **never blocks the caller**: if the queue is already over
+        its byte budget, the artifact is dropped with a warning rather than applying
+        backpressure. A `sync` submit uploads inline (and so blocks) by the caller's
+        explicit choice. Never raises — upload failures are handled internally.
+        """
+    def flush(self, timeout: float | None = None) -> bool:
+        """Block until queued background uploads have drained. Returns whether they did."""
+    def shutdown(self, timeout: float = 5.0) -> None:
+        """Drain in-flight uploads and stop the worker thread."""
diff --git a/logfire-api/logfire_api/_internal/json_encoder.pyi b/logfire-api/logfire_api/_internal/json_encoder.pyi
index 1496d336d..20b7649ca 100644
--- a/logfire-api/logfire_api/_internal/json_encoder.pyi
+++ b/logfire-api/logfire_api/_internal/json_encoder.pyi
@@ -1,8 +1,11 @@
-from .utils import JsonValue as JsonValue, safe_repr as safe_repr
-from _typeshed import Incomplete
 from functools import cache, lru_cache
 from typing import Any
 
+from _typeshed import Incomplete
+
+from .artifacts import Artifact as Artifact
+from .utils import JsonValue as JsonValue, safe_repr as safe_repr
+
 NUMPY_DIMENSION_MAX_SIZE: int
 EncoderFunction: Incomplete
 
diff --git a/logfire-api/logfire_api/_internal/main.pyi b/logfire-api/logfire_api/_internal/main.pyi
index 4bb0d8b67..ec4580a55 100644
--- a/logfire-api/logfire_api/_internal/main.pyi
+++ b/logfire-api/logfire_api/_internal/main.pyi
@@ -1,3 +1,9 @@
+from collections.abc import Iterable, Mapping, Sequence
+from contextlib import AbstractContextManager
+from types import ModuleType
+from typing import Any, Callable, Literal, TypeVar, overload
+from wsgiref.types import WSGIApplication
+
 import anthropic
 import httpx
 import openai
@@ -5,20 +11,76 @@ import opentelemetry.trace as trace_api
 import pydantic_ai
 import pydantic_ai.models
 import requests
-from . import async_ as async_
-from ..integrations.aiohttp_client import RequestHook as AiohttpClientRequestHook, ResponseHook as AiohttpClientResponseHook
-from ..integrations.flask import CommenterOptions as FlaskCommenterOptions, RequestHook as FlaskRequestHook, ResponseHook as FlaskResponseHook
-from ..integrations.httpx import AsyncRequestHook as HttpxAsyncRequestHook, AsyncResponseHook as HttpxAsyncResponseHook, RequestHook as HttpxRequestHook, ResponseHook as HttpxResponseHook
+from anthropic.lib.bedrock import AnthropicBedrock as _AnthropicBedrock, AsyncAnthropicBedrock as _AsyncAnthropicBedrock
+from django.http import HttpRequest as HttpRequest, HttpResponse as HttpResponse
+from fastapi import FastAPI
+from flask.app import Flask
+from opentelemetry.context import Context as Context
+from opentelemetry.instrumentation.asgi.types import ClientRequestHook, ClientResponseHook, ServerRequestHook
+from opentelemetry.metrics import CallbackT as CallbackT, Counter, Histogram, UpDownCounter, _Gauge as Gauge
+from opentelemetry.sdk.trace import ReadableSpan, Span
+from opentelemetry.trace import SpanContext, SpanKind
+from opentelemetry.util import types as otel_types
+from pydantic_evals.reporting import EvaluationReport
+from pymongo.monitoring import (
+    CommandFailedEvent as CommandFailedEvent,
+    CommandStartedEvent as CommandStartedEvent,
+    CommandSucceededEvent as CommandSucceededEvent,
+)
+from sqlalchemy import Engine
+from sqlalchemy.ext.asyncio import AsyncEngine
+from starlette.applications import Starlette
+from starlette.requests import Request as Request
+from starlette.websockets import WebSocket as WebSocket
+from surrealdb.connections.async_template import AsyncTemplate
+from surrealdb.connections.sync_template import SyncTemplate
+from typing_extensions import LiteralString, ParamSpec, Unpack
+
+from ..integrations.aiohttp_client import (
+    RequestHook as AiohttpClientRequestHook,
+    ResponseHook as AiohttpClientResponseHook,
+)
+from ..integrations.flask import (
+    CommenterOptions as FlaskCommenterOptions,
+    RequestHook as FlaskRequestHook,
+    ResponseHook as FlaskResponseHook,
+)
+from ..integrations.httpx import (
+    AsyncRequestHook as HttpxAsyncRequestHook,
+    AsyncResponseHook as HttpxAsyncResponseHook,
+    RequestHook as HttpxRequestHook,
+    ResponseHook as HttpxResponseHook,
+)
 from ..integrations.psycopg import CommenterOptions as PsycopgCommenterOptions
 from ..integrations.redis import RequestHook as RedisRequestHook, ResponseHook as RedisResponseHook
 from ..integrations.sqlalchemy import CommenterOptions as SQLAlchemyCommenterOptions
 from ..integrations.wsgi import RequestHook as WSGIRequestHook, ResponseHook as WSGIResponseHook
-from ..variables import ResolveFunction as ResolveFunction, ValidationReport as ValidationReport, Variable as Variable, VariablesConfig as VariablesConfig
+from ..variables import (
+    ResolveFunction as ResolveFunction,
+    ValidationReport as ValidationReport,
+    Variable as Variable,
+    VariablesConfig as VariablesConfig,
+)
 from ..version import VERSION as VERSION
+from . import async_ as async_
+from .artifacts import Artifact as Artifact
 from .auto_trace import AutoTraceModule as AutoTraceModule, install_auto_tracing as install_auto_tracing
 from .config import GLOBAL_CONFIG as GLOBAL_CONFIG, LogfireConfig as LogfireConfig
 from .config_params import PydanticPluginRecordValues as PydanticPluginRecordValues
-from .constants import ATTRIBUTES_JSON_SCHEMA_KEY as ATTRIBUTES_JSON_SCHEMA_KEY, ATTRIBUTES_LOG_LEVEL_NUM_KEY as ATTRIBUTES_LOG_LEVEL_NUM_KEY, ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY, ATTRIBUTES_MESSAGE_TEMPLATE_KEY as ATTRIBUTES_MESSAGE_TEMPLATE_KEY, ATTRIBUTES_SAMPLE_RATE_KEY as ATTRIBUTES_SAMPLE_RATE_KEY, ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY, ATTRIBUTES_TAGS_KEY as ATTRIBUTES_TAGS_KEY, DISABLE_CONSOLE_KEY as DISABLE_CONSOLE_KEY, LEVEL_NUMBERS as LEVEL_NUMBERS, LevelName as LevelName, OTLP_MAX_INT_SIZE as OTLP_MAX_INT_SIZE, log_level_attributes as log_level_attributes
+from .constants import (
+    ATTRIBUTES_JSON_SCHEMA_KEY as ATTRIBUTES_JSON_SCHEMA_KEY,
+    ATTRIBUTES_LOG_LEVEL_NUM_KEY as ATTRIBUTES_LOG_LEVEL_NUM_KEY,
+    ATTRIBUTES_MESSAGE_KEY as ATTRIBUTES_MESSAGE_KEY,
+    ATTRIBUTES_MESSAGE_TEMPLATE_KEY as ATTRIBUTES_MESSAGE_TEMPLATE_KEY,
+    ATTRIBUTES_SAMPLE_RATE_KEY as ATTRIBUTES_SAMPLE_RATE_KEY,
+    ATTRIBUTES_SPAN_TYPE_KEY as ATTRIBUTES_SPAN_TYPE_KEY,
+    ATTRIBUTES_TAGS_KEY as ATTRIBUTES_TAGS_KEY,
+    DISABLE_CONSOLE_KEY as DISABLE_CONSOLE_KEY,
+    LEVEL_NUMBERS as LEVEL_NUMBERS,
+    OTLP_MAX_INT_SIZE as OTLP_MAX_INT_SIZE,
+    LevelName as LevelName,
+    log_level_attributes as log_level_attributes,
+)
 from .formatter import logfire_format as logfire_format, logfire_format_with_magic as logfire_format_with_magic
 from .instrument import instrument as instrument
 from .integrations.asgi import ASGIApp as ASGIApp, ASGIInstrumentKwargs as ASGIInstrumentKwargs
@@ -29,36 +91,26 @@ from .integrations.psycopg import Psycopg2Connection as Psycopg2Connection, Psyc
 from .integrations.sqlite3 import SQLite3Connection as SQLite3Connection
 from .integrations.system_metrics import Base as SystemMetricsBase, Config as SystemMetricsConfig
 from .json_encoder import logfire_json_dumps as logfire_json_dumps
-from .json_schema import JsonSchemaProperties as JsonSchemaProperties, attributes_json_schema as attributes_json_schema, attributes_json_schema_properties as attributes_json_schema_properties, create_json_schema as create_json_schema
+from .json_schema import (
+    JsonSchemaProperties as JsonSchemaProperties,
+    attributes_json_schema as attributes_json_schema,
+    attributes_json_schema_properties as attributes_json_schema_properties,
+    create_json_schema as create_json_schema,
+)
 from .metrics import ProxyMeterProvider as ProxyMeterProvider
 from .stack_info import get_user_stack_info as get_user_stack_info
-from .tracer import ProxyTracerProvider as ProxyTracerProvider, _ProxyTracer, set_exception_status as set_exception_status
-from .utils import SysExcInfo as SysExcInfo, get_version as get_version, handle_internal_errors as handle_internal_errors, log_internal_error as log_internal_error, uniquify_sequence as uniquify_sequence
-from anthropic.lib.bedrock import AnthropicBedrock as _AnthropicBedrock, AsyncAnthropicBedrock as _AsyncAnthropicBedrock
-from collections.abc import Iterable, Mapping, Sequence
-from contextlib import AbstractContextManager
-from django.http import HttpRequest as HttpRequest, HttpResponse as HttpResponse
-from fastapi import FastAPI
-from flask.app import Flask
-from opentelemetry.context import Context as Context
-from opentelemetry.instrumentation.asgi.types import ClientRequestHook, ClientResponseHook, ServerRequestHook
-from opentelemetry.metrics import CallbackT as CallbackT, Counter, Histogram, UpDownCounter, _Gauge as Gauge
-from opentelemetry.sdk.trace import ReadableSpan, Span
-from opentelemetry.trace import SpanContext, SpanKind
-from opentelemetry.util import types as otel_types
-from pydantic_evals.reporting import EvaluationReport
-from pymongo.monitoring import CommandFailedEvent as CommandFailedEvent, CommandStartedEvent as CommandStartedEvent, CommandSucceededEvent as CommandSucceededEvent
-from sqlalchemy import Engine
-from sqlalchemy.ext.asyncio import AsyncEngine
-from starlette.applications import Starlette
-from starlette.requests import Request as Request
-from starlette.websockets import WebSocket as WebSocket
-from surrealdb.connections.async_template import AsyncTemplate
-from surrealdb.connections.sync_template import SyncTemplate
-from types import ModuleType
-from typing import Any, Callable, Literal, TypeVar, overload
-from typing_extensions import LiteralString, ParamSpec, Unpack
-from wsgiref.types import WSGIApplication
+from .tracer import (
+    ProxyTracerProvider as ProxyTracerProvider,
+    _ProxyTracer,
+    set_exception_status as set_exception_status,
+)
+from .utils import (
+    SysExcInfo as SysExcInfo,
+    get_version as get_version,
+    handle_internal_errors as handle_internal_errors,
+    log_internal_error as log_internal_error,
+    uniquify_sequence as uniquify_sequence,
+)
 
 ExcInfo = SysExcInfo | BaseException | bool | None
 T = TypeVar('T')
@@ -525,7 +577,7 @@ class Logfire:
                 i.e. it's not necessary to use this as a context manager.
         """
     def instrument_openai(self, openai_client: openai.OpenAI | openai.AsyncOpenAI | type[openai.OpenAI] | type[openai.AsyncOpenAI] | None = None, *, suppress_other_instrumentation: bool = True, version: SemconvVersion | Sequence[SemconvVersion] = 1) -> AbstractContextManager[None]:
-        '''Instrument an OpenAI client so that spans are automatically created for each request.
+        """Instrument an OpenAI client so that spans are automatically created for each request.
 
         This instruments the [standard OpenAI SDK](https://pypi.org/project/openai/) package, for instrumentation
         of the OpenAI "agents" framework, see [`instrument_openai_agents()`][logfire.Logfire.instrument_openai_agents].
@@ -587,7 +639,7 @@ class Logfire:
         Returns:
             A context manager that will revert the instrumentation when exited.
                 Use of this context manager is optional.
-        '''
+        """
     def instrument_openai_agents(self) -> None:
         """Instrument the [`agents`](https://github.com/openai/openai-agents-python) framework from OpenAI.
 
@@ -595,7 +647,7 @@ class Logfire:
         see [`instrument_openai()`][logfire.Logfire.instrument_openai].
         """
     def instrument_anthropic(self, anthropic_client: anthropic.Anthropic | anthropic.AsyncAnthropic | _AnthropicBedrock | _AsyncAnthropicBedrock | type[anthropic.Anthropic] | type[anthropic.AsyncAnthropic] | type[_AnthropicBedrock] | type[_AsyncAnthropicBedrock] | None = None, *, suppress_other_instrumentation: bool = True, version: SemconvVersion | Sequence[SemconvVersion] = 1) -> AbstractContextManager[None]:
-        '''Instrument an Anthropic client so that spans are automatically created for each request.
+        """Instrument an Anthropic client so that spans are automatically created for each request.
 
         The following methods are instrumented for both the sync and async clients:
 
@@ -652,7 +704,7 @@ class Logfire:
         Returns:
             A context manager that will revert the instrumentation when exited.
                 Use of this context manager is optional.
-        '''
+        """
     def instrument_google_genai(self, **kwargs: Any):
         """Instrument the [Google Gen AI SDK (`google-genai`)](https://googleapis.github.io/python-genai/).
 
@@ -1346,7 +1398,7 @@ class Logfire:
             ```
         """
     def variables_push_config(self, config: VariablesConfig, *, mode: Literal['merge', 'replace'] = 'merge', dry_run: bool = False, yes: bool = False) -> bool:
-        '''Push a VariablesConfig to the configured provider.
+        """Push a VariablesConfig to the configured provider.
 
         This method pushes a complete VariablesConfig (including labels and rollouts)
         to the provider. It\'s useful for:
@@ -1375,9 +1427,9 @@ class Logfire:
             # Or merge just a subset of variables
             logfire.variables_push_config(config, mode=\'merge\')
             ```
-        '''
+        """
     def variables_pull_config(self) -> VariablesConfig:
-        '''Pull the current variable configuration from the provider.
+        """Pull the current variable configuration from the provider.
 
         This method fetches the complete configuration from the provider,
         useful for generating local copies of the config that can be modified.
@@ -1393,9 +1445,9 @@ class Logfire:
             config = logfire.variables_pull_config()
             print(config.model_dump_json(indent=2))
             ```
-        '''
+        """
     def variables_build_config(self, variables: list[Variable[Any]] | None = None) -> VariablesConfig:
-        '''Build a VariablesConfig from registered Variable instances.
+        """Build a VariablesConfig from registered Variable instances.
 
         This creates a minimal config with just the name, schema, and example for each variable.
         No labels or versions are created - use this to build a template config that can be edited.
@@ -1417,7 +1469,7 @@ class Logfire:
             config = logfire.variables_build_config()
             print(config.model_dump_json(indent=2))
             ```
-        '''
+        """
 
 class FastLogfireSpan:
     """A simple version of `LogfireSpan` optimized for auto-tracing."""
diff --git a/logfire-api/logfire_api/variables/abstract.pyi b/logfire-api/logfire_api/variables/abstract.pyi
index 08212c9a3..311d60cda 100644
--- a/logfire-api/logfire_api/variables/abstract.pyi
+++ b/logfire-api/logfire_api/variables/abstract.pyi
@@ -1,12 +1,14 @@
-import logfire
-from _typeshed import Incomplete
 from abc import ABC, abstractmethod
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
-from logfire.variables.config import VariableConfig, VariableTypeConfig, VariablesConfig
-from logfire.variables.variable import Variable
 from typing import Any, Generic, TypeVar
 
+from _typeshed import Incomplete
+
+import logfire
+from logfire.variables.config import VariableConfig, VariablesConfig, VariableTypeConfig
+from logfire.variables.variable import Variable
+
 __all__ = ['ResolvedVariable', 'SyncMode', 'ValidationReport', 'VariableProvider', 'NoOpVariableProvider', 'VariableWriteError', 'VariableNotFoundError', 'VariableAlreadyExistsError']
 
 SyncMode: Incomplete
@@ -22,22 +24,24 @@ class VariableAlreadyExistsError(VariableWriteError):
 
 @dataclass(kw_only=True)
 class ResolvedVariable(Generic[T_co]):
-    '''Details about a variable resolution including value, label, version, and any errors.
+    """Details about a variable resolution including value, label, version, and any errors.
 
     This class can be used as a context manager. When used as a context manager, it
-    automatically sets baggage with the variable name and label, enabling downstream
-    spans and logs to be associated with the variable resolution that was active at the time.
+    automatically sets baggage with the variable name, label, and (when applicable)
+    version, enabling downstream spans and logs to be associated with the variable
+    resolution that was active at the time.
 
     Example:
         ```python skip="true"
         my_var = logfire.var(name=\'my_var\', type=str, default=\'default\')
         with my_var.get() as details:
             # Inside this context, baggage is set with:
-            # logfire.variables.my_var = <label> (or \'<code_default>\' if no label)
+            #   logfire.variables.my_var          = <label> (or \'<code_default>\' if no label)
+            #   logfire.variables.my_var.version  = <version> (only when a versioned value was resolved)
             value = details.value
-            # Any spans/logs created here will have the baggage attached
+            # Any spans/logs created here will have the baggage attached.
         ```
-    '''
+    """
     name: str
     value: T_co
     label: str | None = ...
@@ -94,7 +98,7 @@ class DescriptionDifference:
 
 @dataclass
 class ValidationReport:
-    '''Report of variable validation results.
+    """Report of variable validation results.
 
     This class contains the results of validating variable definitions against
     a provider\'s configuration. It can be used to check for errors programmatically
@@ -107,7 +111,7 @@ class ValidationReport:
             print(report.format())
             sys.exit(1)
         ```
-    '''
+    """
     errors: list[LabelValidationError]
     variables_checked: int
     variables_not_on_server: list[str]
@@ -315,7 +319,7 @@ class VariableProvider(ABC):
             True if changes were applied (or would be applied in dry_run mode), False otherwise.
         """
     def validate_variables(self, variables: Sequence[Variable[object]]) -> ValidationReport:
-        '''Validate that provider-side variable label values match local type definitions.
+        """Validate that provider-side variable label values match local type definitions.
 
         This method fetches the current variable configuration from the provider and
         validates that all label values can be deserialized to the expected types
@@ -335,7 +339,7 @@ class VariableProvider(ABC):
                 print(report.format())
                 sys.exit(1)
             ```
-        '''
+        """
     def list_variable_types(self) -> dict[str, VariableTypeConfig]:
         """List all variable types from the provider.
 
@@ -364,7 +368,7 @@ class VariableProvider(ABC):
             The created or updated VariableTypeConfig.
         """
     def push_variable_types(self, types: Sequence[type[Any] | tuple[type[Any], str]], *, dry_run: bool = False, yes: bool = False, strict: bool = False) -> bool:
-        '''Push variable type definitions to this provider.
+        """Push variable type definitions to this provider.
 
         This method syncs local type definitions with the provider:
         - Creates new types that don\'t exist in the provider
@@ -400,7 +404,7 @@ class VariableProvider(ABC):
             # Push with explicit name
             provider.push_variable_types([(FeatureConfig, \'my_feature_config\')])
             ```
-        '''
+        """
 
 @dataclass
 class NoOpVariableProvider(VariableProvider):
diff --git a/logfire/__init__.py b/logfire/__init__.py
index fb03376ea..b83cff122 100644
--- a/logfire/__init__.py
+++ b/logfire/__init__.py
@@ -8,6 +8,7 @@
 from logfire.sampling import SamplingOptions
 
 from . import variables as variables
+from ._internal.artifacts import Artifact, UploadMode
 from ._internal.auto_trace import AutoTraceModule
 from ._internal.auto_trace.rewrite_ast import no_auto_trace
 from ._internal.baggage import get_baggage, set_baggage
@@ -213,4 +214,6 @@ def loguru_handler() -> Any:
     'get_context',
     'attach_context',
     'url_from_eval',
+    'Artifact',
+    'UploadMode',
 )
diff --git a/logfire/_internal/artifacts.py b/logfire/_internal/artifacts.py
new file mode 100644
index 000000000..7deefe8b2
--- /dev/null
+++ b/logfire/_internal/artifacts.py
@@ -0,0 +1,258 @@
+"""The `Artifact` type — binary blobs attached to spans out of band.
+
+An `Artifact` wraps a binary blob (image, audio, PDF, large JSON, ...). When it is logged
+as a span attribute, Logfire stores the blob in object storage and embeds only a small
+reference object in the span, so the blob never travels through the telemetry pipeline
+and is not subject to attribute size limits.
+
+Artifacts are content-addressed: the SDK computes the blob's sha256 and that is its
+identity. The same blob logged repeatedly is uploaded and stored once.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import mimetypes
+import os
+from abc import ABC, abstractmethod
+from typing import IO, Any, Literal
+
+__all__ = 'Artifact', 'UploadMode'
+
+UploadMode = Literal['sync', 'background']
+"""When an artifact's blob bytes are uploaded, relative to the logging call.
+
+- `sync`: upload inline — the logging call returns only once the blob is stored, so the
+  source bytes/file/handle may be freed, closed, or deleted immediately afterwards.
+- `background`: hand the upload to a background thread — the logging call never blocks.
+  Near-free for file-path sources (re-read from disk at upload time); holds the bytes in
+  memory for in-memory `bytes` sources until the upload drains. If uploads cannot keep
+  up, queued artifacts are dropped with a warning rather than stalling the program — use
+  `sync` when delivery must be guaranteed.
+"""
+
+# The discriminator stamped on the reference object embedded in span attributes; the
+# backend and frontend key off this to recognise an artifact reference.
+ARTIFACT_REFERENCE_TYPE = 'logfire.artifact'
+
+_HASH_CHUNK_SIZE = 1024 * 1024
+
+
+class ArtifactSource(ABC):
+    """A source of artifact bytes — normalises bytes, files, and handles to one surface.
+
+    Deliberately small so that streaming sources can be added later as a new subclass
+    without touching `Artifact`, the upload handshake, or the backend.
+    """
+
+    @abstractmethod
+    def digest(self) -> tuple[str, int]:
+        """Return `(sha256_hex, size_bytes)` for the content."""
+
+    @abstractmethod
+    def read(self) -> bytes:
+        """Return the full content as bytes, for upload."""
+
+
+class _BytesSource(ArtifactSource):
+    """An in-memory blob."""
+
+    def __init__(self, data: bytes) -> None:
+        self._data = bytes(data)
+
+    def digest(self) -> tuple[str, int]:
+        return hashlib.sha256(self._data).hexdigest(), len(self._data)
+
+    def read(self) -> bytes:
+        return self._data
+
+
+class _PathSource(ArtifactSource):
+    """A file on disk.
+
+    Hashed and uploaded by reading the path, so a `background` upload of a file path
+    holds no bytes in memory.
+    """
+
+    def __init__(self, path: str | os.PathLike[str]) -> None:
+        self._path = os.fspath(path)
+
+    def digest(self) -> tuple[str, int]:
+        hasher = hashlib.sha256()
+        size = 0
+        with open(self._path, 'rb') as file:
+            while chunk := file.read(_HASH_CHUNK_SIZE):
+                hasher.update(chunk)
+                size += len(chunk)
+        return hasher.hexdigest(), size
+
+    def read(self) -> bytes:
+        with open(self._path, 'rb') as file:
+            return file.read()
+
+
+class Artifact:
+    """A binary blob to attach to a span — an image, audio clip, PDF, large JSON, etc.
+
+    Pass an `Artifact` as a span or log attribute value. Logfire uploads the blob to
+    object storage out of band and embeds a small reference in the span.
+
+    Examples:
+        ```python
+        import logfire
+
+        logfire.configure()
+
+        # From a file path.
+        logfire.info('chart generated', chart=logfire.Artifact.from_file('chart.png'))
+
+        # From in-memory bytes.
+        logfire.info('thumbnail', image=logfire.Artifact(png_bytes, content_type='image/png'))
+
+        # From an open binary handle (including temporary / spooled files).
+        with open('report.pdf', 'rb') as handle:
+            logfire.info('report', report=logfire.Artifact.from_file_handle(handle))
+        ```
+    """
+
+    def __init__(
+        self,
+        data: bytes,
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        upload: UploadMode = 'background',
+    ) -> None:
+        """Create an artifact from in-memory bytes.
+
+        Args:
+            data: The blob bytes.
+            filename: Optional original filename, shown in the UI and used to guess the
+                content type.
+            content_type: MIME type of the blob. Guessed from `filename` when omitted,
+                falling back to `application/octet-stream`.
+            upload: When to upload the blob — see [`UploadMode`][logfire.UploadMode].
+                Defaults to `background`.
+        """
+        self._configure(
+            _BytesSource(data), filename=filename, content_type=content_type, upload=upload, guess_from=filename
+        )
+
+    @classmethod
+    def from_file(
+        cls,
+        path: str | os.PathLike[str],
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        upload: UploadMode = 'background',
+    ) -> Artifact:
+        """Create an artifact from a file path.
+
+        The file is read once to hash it and again to upload it, so a `background`
+        upload of a file path holds no bytes in memory.
+
+        Args:
+            path: Path to the file.
+            filename: Original filename to record. Defaults to the basename of `path`.
+            content_type: MIME type. Guessed from the path/filename when omitted.
+            upload: When to upload the blob — see [`UploadMode`][logfire.UploadMode].
+        """
+        artifact = cls.__new__(cls)
+        artifact._configure(
+            _PathSource(path),
+            filename=filename or os.path.basename(os.fspath(path)),
+            content_type=content_type,
+            upload=upload,
+            guess_from=filename or os.fspath(path),
+        )
+        return artifact
+
+    @classmethod
+    def from_file_handle(
+        cls,
+        handle: IO[bytes],
+        *,
+        filename: str | None = None,
+        content_type: str | None = None,
+        upload: UploadMode = 'background',
+    ) -> Artifact:
+        """Create an artifact from an open binary file handle.
+
+        Works with any binary handle, including `tempfile.SpooledTemporaryFile` and
+        `tempfile.NamedTemporaryFile`. The handle is read in full immediately, so the
+        caller may close it as soon as this returns.
+
+        Args:
+            handle: An open binary (`'rb'`) file-like object.
+            filename: Original filename to record. Defaults to the handle's `name`.
+            content_type: MIME type. Guessed from the filename when omitted.
+            upload: When to upload the blob — see [`UploadMode`][logfire.UploadMode].
+        """
+        artifact = cls.__new__(cls)
+        handle_name = getattr(handle, 'name', None)
+        resolved_name = filename or (os.path.basename(handle_name) if isinstance(handle_name, str) else None)
+        artifact._configure(
+            _BytesSource(handle.read()),
+            filename=resolved_name,
+            content_type=content_type,
+            upload=upload,
+            guess_from=resolved_name or handle_name,
+        )
+        return artifact
+
+    def _configure(
+        self,
+        source: ArtifactSource,
+        *,
+        filename: str | None,
+        content_type: str | None,
+        upload: UploadMode,
+        guess_from: Any,
+    ) -> None:
+        self._source = source
+        self.filename = filename
+        self.upload: UploadMode = upload
+        self.content_type = content_type or _guess_content_type(guess_from)
+        self._digest: tuple[str, int] | None = None
+
+    @property
+    def sha256(self) -> str:
+        """The hex sha256 of the blob — its content-addressed identity."""
+        return self._compute()[0]
+
+    @property
+    def size_bytes(self) -> int:
+        """The size of the blob in bytes."""
+        return self._compute()[1]
+
+    def _compute(self) -> tuple[str, int]:
+        if self._digest is None:
+            self._digest = self._source.digest()
+        return self._digest
+
+    def read(self) -> bytes:
+        """Read the full blob into memory (used by the uploader)."""
+        return self._source.read()
+
+    def reference(self) -> dict[str, Any]:
+        """The reference object embedded into the span attribute in place of the blob."""
+        sha256, size_bytes = self._compute()
+        reference: dict[str, Any] = {
+            'type': ARTIFACT_REFERENCE_TYPE,
+            'sha256': sha256,
+            'content_type': self.content_type,
+            'size_bytes': size_bytes,
+        }
+        if self.filename is not None:
+            reference['filename'] = self.filename
+        return reference
+
+
+def _guess_content_type(name: Any) -> str:
+    """Guess a MIME type from a filename/path, defaulting to `application/octet-stream`."""
+    if isinstance(name, str):
+        guessed, _ = mimetypes.guess_type(name)
+        if guessed:
+            return guessed
+    return 'application/octet-stream'
diff --git a/logfire/_internal/config.py b/logfire/_internal/config.py
index 05c55488c..e3e4ab605 100644
--- a/logfire/_internal/config.py
+++ b/logfire/_internal/config.py
@@ -71,6 +71,7 @@
 
 from ..propagate import NoExtractTraceContextPropagator, WarnOnExtractTraceContextPropagator
 from ..types import ExceptionCallback
+from .artifacts import Artifact
 from .client import InvalidProjectName, LogfireClient, ProjectAlreadyExists
 from .config_params import ParamManager, PydanticPluginRecordValues, normalize_token
 from .constants import (
@@ -85,6 +86,7 @@
     RESOURCE_ATTRIBUTES_VERSION,
     LevelName,
 )
+from .exporters.artifact_uploader import ArtifactUploader
 from .exporters.console import (
     ConsoleColorsValues,
     ConsoleLogExporter,
@@ -936,6 +938,8 @@ def __init__(
         self._has_set_providers = False
         self._initialized = False
         self._lock = RLock()
+        # Uploads artifact blobs out of band; created in `_initialize` once a token is known.
+        self._artifact_uploader: ArtifactUploader | None = None
 
     def configure(
         self,
@@ -1233,6 +1237,14 @@ def check_tokens():
                         # This line is just to make sure.
                         session.headers.update(headers)
 
+                    # Artifact blobs go to the backend REST API out of band from
+                    # telemetry, using the first token's project and region.
+                    first_token = token_list[0]
+                    self._artifact_uploader = ArtifactUploader(
+                        base_url=self.advanced.generate_base_url(first_token),
+                        token=first_token,
+                    )
+
             deferred_processors: list[SpanProcessor] = []
             if processors_with_pending_spans:
                 pending_multiprocessor = SynchronousMultiSpanProcessor()
@@ -1411,8 +1423,19 @@ def force_flush(self, timeout_millis: int = 30_000) -> bool:
         """
         self._meter_provider.force_flush(timeout_millis)
         self._logger_provider.force_flush(timeout_millis)
+        if self._artifact_uploader is not None:
+            self._artifact_uploader.flush(timeout_millis / 1000)
         return self._tracer_provider.force_flush(timeout_millis)
 
+    def submit_artifact(self, artifact: Artifact) -> None:
+        """Upload an artifact's blob out of band — inline (`sync`) or queued (`background`).
+
+        No-op when there is no configured token (and hence no uploader): the artifact
+        reference is still recorded on the span, but the blob cannot be uploaded.
+        """
+        if self._artifact_uploader is not None:
+            self._artifact_uploader.submit(artifact)
+
     def get_tracer_provider(self) -> ProxyTracerProvider:
         """Get a tracer provider from this `LogfireConfig`.
 
diff --git a/logfire/_internal/exporters/artifact_uploader.py b/logfire/_internal/exporters/artifact_uploader.py
new file mode 100644
index 000000000..036ecd9bd
--- /dev/null
+++ b/logfire/_internal/exporters/artifact_uploader.py
@@ -0,0 +1,152 @@
+"""Background uploader for artifact blobs.
+
+Artifact blobs are uploaded out of band from telemetry: the upload (a register / PUT /
+finalize handshake against the Logfire backend) never blocks span export. A `sync`
+artifact is uploaded inline on the logging thread (the caller's explicit choice); a
+`background` artifact is handed to a worker thread and **never blocks the caller** —
+if the worker's queue is over its byte budget the artifact is dropped with a warning
+rather than applying backpressure.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+import time
+import warnings
+from urllib.parse import urljoin
+
+import requests
+
+from ..artifacts import Artifact
+from ..utils import log_internal_error
+
+# Default ceiling on bytes queued for background upload. When exceeded, `submit` blocks.
+DEFAULT_MAX_QUEUE_BYTES = 64 * 1024 * 1024
+
+# Per-HTTP-request timeout for the upload handshake.
+_REQUEST_TIMEOUT = 30
+
+
+class ArtifactUploader:
+    """Uploads artifact blobs to the Logfire backend.
+
+    Owns a daemon worker thread for `background` artifacts; `sync` artifacts are uploaded
+    on the calling thread.
+    """
+
+    def __init__(self, *, base_url: str, token: str, max_queue_bytes: int = DEFAULT_MAX_QUEUE_BYTES) -> None:
+        self._base_url = base_url
+        self._auth = {'Authorization': f'Bearer {token}'}
+        self._max_queue_bytes = max_queue_bytes
+        self._queue: queue.Queue[Artifact | None] = queue.Queue()
+        # Guards `_queued_bytes`; notified whenever an upload finishes or is dequeued.
+        self._capacity = threading.Condition()
+        self._queued_bytes = 0
+        self._thread = threading.Thread(target=self._run, name='logfire-artifact-uploader', daemon=True)
+        self._thread.start()
+
+    def submit(self, artifact: Artifact) -> None:
+        """Upload an artifact's blob — inline for `sync`, queued for `background`.
+
+        A `background` submit **never blocks the caller**: if the queue is already over
+        its byte budget, the artifact is dropped with a warning rather than applying
+        backpressure. A `sync` submit uploads inline (and so blocks) by the caller's
+        explicit choice. Never raises — upload failures are handled internally.
+        """
+        if artifact.upload == 'sync':
+            self._run_upload(artifact)
+            return
+
+        size = artifact.size_bytes
+        with self._capacity:
+            # Drop rather than block: artifact uploads must never stall the program.
+            # An empty queue always admits one artifact, so a lone large blob still
+            # uploads even if it alone exceeds the budget.
+            if self._queued_bytes and self._queued_bytes + size > self._max_queue_bytes:
+                warnings.warn(
+                    f'Artifact upload queue is full ({self._queued_bytes} bytes queued); '
+                    f'dropping background artifact ({size} bytes). '
+                    'Pass upload="sync" to guarantee delivery.',
+                )
+                return
+            self._queued_bytes += size
+        self._queue.put(artifact)
+
+    def flush(self, timeout: float | None = None) -> bool:
+        """Block until queued background uploads have drained. Returns whether they did."""
+        deadline = None if timeout is None else time.monotonic() + timeout
+        with self._capacity:
+            while self._queued_bytes:
+                remaining = None if deadline is None else deadline - time.monotonic()
+                if remaining is not None and remaining <= 0:
+                    return False
+                self._capacity.wait(remaining)
+        return True
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        """Drain in-flight uploads and stop the worker thread."""
+        self.flush(timeout)
+        self._queue.put(None)
+        self._thread.join(timeout=timeout)
+
+    def _run(self) -> None:
+        while True:
+            artifact = self._queue.get()
+            if artifact is None:
+                return
+            try:
+                self._run_upload(artifact)
+            finally:
+                with self._capacity:
+                    self._queued_bytes -= artifact.size_bytes
+                    self._capacity.notify_all()
+
+    def _run_upload(self, artifact: Artifact) -> None:
+        try:
+            self._upload(artifact)
+        except requests.RequestException:
+            # Network/HTTP failures are operational, not bugs: the artifact reference is
+            # still recorded on the span, the blob just isn't stored. Best-effort upload —
+            # never crash the caller's logging call over it.
+            pass
+        except Exception:
+            log_internal_error()
+
+    def _upload(self, artifact: Artifact) -> None:
+        """Run the register / PUT / finalize handshake for one artifact."""
+        reference = artifact.reference()
+        sha256 = reference['sha256']
+
+        registered = requests.post(
+            urljoin(self._base_url, '/v1/artifacts'),
+            json={
+                'sha256': sha256,
+                'size_bytes': reference['size_bytes'],
+                'content_type': reference['content_type'],
+                'filename': reference.get('filename'),
+            },
+            headers=self._auth,
+            timeout=_REQUEST_TIMEOUT,
+        )
+        registered.raise_for_status()
+        body = registered.json()
+        if body['status'] == 'exists':
+            # The blob is already stored (content-addressed dedup) — nothing to upload.
+            return
+
+        target = body['upload']
+        # Signed object-store URLs are self-authenticating; sending the bearer token
+        # there can break the signature, so only the backend `/blob` endpoint gets auth.
+        put_headers = self._auth if target['requires_auth'] else {}
+        put = requests.request(
+            target['method'], target['url'], data=artifact.read(), headers=put_headers, timeout=_REQUEST_TIMEOUT
+        )
+        put.raise_for_status()
+
+        finalized = requests.post(
+            urljoin(self._base_url, f'/v1/artifacts/{sha256}/finalize'),
+            headers=self._auth,
+            timeout=_REQUEST_TIMEOUT,
+        )
+        finalized.raise_for_status()
diff --git a/logfire/_internal/json_encoder.py b/logfire/_internal/json_encoder.py
index f48956953..7d7dfaf56 100644
--- a/logfire/_internal/json_encoder.py
+++ b/logfire/_internal/json_encoder.py
@@ -16,6 +16,7 @@
 from typing import Any
 from uuid import UUID
 
+from .artifacts import Artifact
 from .utils import JsonValue, safe_repr
 
 NUMPY_DIMENSION_MAX_SIZE = 10
@@ -214,6 +215,8 @@ def encoder_by_type() -> dict[type[Any], EncoderFunction]:
         Pattern: lambda o, seen: to_json_value(o.pattern, seen),
         UUID: _to_str,
         Exception: _to_str,
+        # An artifact serialises to its reference object; the blob is uploaded separately.
+        Artifact: lambda o, _: o.reference(),
     }
     with contextlib.suppress(ModuleNotFoundError):
         import pydantic
diff --git a/logfire/_internal/json_schema.py b/logfire/_internal/json_schema.py
index ea1d2e6a6..aee722655 100644
--- a/logfire/_internal/json_schema.py
+++ b/logfire/_internal/json_schema.py
@@ -30,6 +30,7 @@
 from types import GeneratorType
 from typing import Any, NewType, cast
 
+from .artifacts import Artifact
 from .constants import ATTRIBUTES_SCRUBBED_KEY
 from .json_encoder import is_attrs, is_sqlalchemy, to_json_value
 from .stack_info import STACK_INFO_KEYS
@@ -61,6 +62,7 @@ def type_to_schema() -> dict[type[Any], JsonDict | Callable[[Any, set[int]], Jso
         range: {'type': 'array', 'x-python-datatype': 'range'},
         PosixPath: {'type': 'string', 'format': 'path', 'x-python-datatype': 'PosixPath'},
         Exception: _exception_schema,
+        Artifact: {'type': 'object', 'x-python-datatype': 'logfire-artifact'},
     }
     with contextlib.suppress(ModuleNotFoundError):
         import pydantic
diff --git a/logfire/_internal/main.py b/logfire/_internal/main.py
index cc674c0fd..a159d8c94 100644
--- a/logfire/_internal/main.py
+++ b/logfire/_internal/main.py
@@ -34,6 +34,7 @@
 
 from ..version import VERSION
 from . import async_
+from .artifacts import Artifact
 from .auto_trace import AutoTraceModule, install_auto_tracing
 from .config import GLOBAL_CONFIG, LogfireConfig
 from .config_params import PydanticPluginRecordValues
@@ -3130,6 +3131,10 @@ def prepare_otlp_attributes(attributes: dict[str, Any]) -> dict[str, otel_types.
 
 def prepare_otlp_attribute(value: Any) -> otel_types.AttributeValue:
     """Convert a user attribute to an OpenTelemetry compatible type."""
+    if isinstance(value, Artifact):
+        # Upload the blob out of band; the span attribute only carries the reference.
+        GLOBAL_CONFIG.submit_artifact(value)
+        return logfire_json_dumps(value)
     if isinstance(value, Enum):
         return logfire_json_dumps(value)
     elif isinstance(value, int):
diff --git a/mkdocs.yml b/mkdocs.yml
index 939d60350..7a0625624 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -254,6 +254,7 @@ nav:
               - Datasets: reference/api/datasets.md
           - SDK CLI: reference/cli.md
           - Examples: reference/examples.md
+          - Artifacts: reference/advanced/artifacts.md
           - Baggage: reference/advanced/baggage.md
           - Generators: reference/advanced/generators.md
           - Aggregating Metrics in Spans: reference/advanced/metrics-in-spans.md
@@ -503,6 +504,7 @@ plugins:
           - reference/api/*.md
           - reference/cli.md
           - reference/examples.md
+          - reference/advanced/artifacts.md
           - reference/advanced/baggage.md
           - reference/advanced/generators.md
           - reference/advanced/metrics-in-spans.md
diff --git a/tests/test_artifacts.py b/tests/test_artifacts.py
new file mode 100644
index 000000000..c2658a179
--- /dev/null
+++ b/tests/test_artifacts.py
@@ -0,0 +1,229 @@
+"""Tests for `logfire.Artifact` — the JSON-schema/encoder hooks and the blob uploader."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import threading
+from pathlib import Path
+from typing import Any
+
+import pytest
+import requests_mock as requests_mock_module
+
+import logfire
+from logfire._internal.artifacts import Artifact
+from logfire._internal.exporters.artifact_uploader import ArtifactUploader
+from logfire._internal.json_encoder import logfire_json_dumps, to_json_value
+from logfire._internal.json_schema import create_json_schema
+from logfire.testing import TestExporter
+
+_BLOB = b'\x89PNG\r\n\x1a\n' + b'logfire-artifact' * 8
+_SHA = hashlib.sha256(_BLOB).hexdigest()
+
+
+# --- Artifact construction ---
+
+
+def test_artifact_from_bytes() -> None:
+    artifact = Artifact(_BLOB, filename='cat.png', content_type='image/png')
+    assert artifact.sha256 == _SHA
+    assert artifact.size_bytes == len(_BLOB)
+    assert artifact.content_type == 'image/png'
+    assert artifact.read() == _BLOB
+    assert artifact.reference() == {
+        'type': 'logfire.artifact',
+        'sha256': _SHA,
+        'content_type': 'image/png',
+        'size_bytes': len(_BLOB),
+        'filename': 'cat.png',
+    }
+
+
+def test_artifact_from_file(tmp_path: Path) -> None:
+    path = tmp_path / 'report.pdf'
+    path.write_bytes(_BLOB)
+    artifact = Artifact.from_file(path)
+    assert artifact.sha256 == _SHA
+    assert artifact.size_bytes == len(_BLOB)
+    assert artifact.filename == 'report.pdf'
+    # content type is inferred from the path extension
+    assert artifact.content_type == 'application/pdf'
+    assert artifact.read() == _BLOB
+
+
+def test_artifact_from_file_handle() -> None:
+    handle = io.BytesIO(_BLOB)
+    artifact = Artifact.from_file_handle(handle, filename='audio.mp3')
+    # the handle is fully read on construction, so closing it does not lose data
+    handle.close()
+    assert artifact.sha256 == _SHA
+    assert artifact.content_type == 'audio/mpeg'
+    assert artifact.read() == _BLOB
+
+
+def test_artifact_content_type_defaults_to_octet_stream() -> None:
+    assert Artifact(_BLOB).content_type == 'application/octet-stream'
+
+
+def test_artifact_upload_mode_defaults_to_background() -> None:
+    assert Artifact(_BLOB).upload == 'background'
+    assert Artifact(_BLOB, upload='sync').upload == 'sync'
+
+
+# --- json_schema / json_encoder hooks ---
+
+
+def test_artifact_json_schema() -> None:
+    assert create_json_schema(Artifact(_BLOB), set()) == {'type': 'object', 'x-python-datatype': 'logfire-artifact'}
+
+
+def test_artifact_json_encoding() -> None:
+    artifact = Artifact(_BLOB, filename='cat.png', content_type='image/png')
+    assert to_json_value(artifact, set()) == artifact.reference()
+    # round-trips through the full dumps path used for span attributes
+    assert json.loads(logfire_json_dumps(artifact)) == artifact.reference()
+
+
+def test_artifact_logged_as_span_attribute(exporter: TestExporter) -> None:
+    """Logging an artifact records the reference object and marks it in the json schema."""
+    logfire.info('got a file', file=Artifact(_BLOB, filename='cat.png', content_type='image/png'))
+
+    (span,) = exporter.exported_spans
+    attributes = span.attributes or {}
+    assert json.loads(attributes['file']) == {  # type: ignore[arg-type]
+        'type': 'logfire.artifact',
+        'sha256': _SHA,
+        'content_type': 'image/png',
+        'size_bytes': len(_BLOB),
+        'filename': 'cat.png',
+    }
+    schema = json.loads(attributes['logfire.json_schema'])  # type: ignore[arg-type]
+    assert schema['properties']['file'] == {'type': 'object', 'x-python-datatype': 'logfire-artifact'}
+
+
+# --- ArtifactUploader ---
+
+
+def _uploader(requests_mock: requests_mock_module.Mocker) -> ArtifactUploader:
+    return ArtifactUploader(base_url='http://test', token='write-tok')
+
+
+def test_uploader_sync_handshake(requests_mock: requests_mock_module.Mocker) -> None:
+    """A sync upload runs register -> PUT -> finalize inline."""
+    register = requests_mock.post(
+        'http://test/v1/artifacts',
+        json={
+            'sha256': _SHA,
+            'status': 'upload',
+            'upload': {'method': 'PUT', 'url': f'http://test/v1/artifacts/{_SHA}/blob', 'requires_auth': True},
+        },
+        status_code=201,
+    )
+    blob = requests_mock.put(f'http://test/v1/artifacts/{_SHA}/blob', status_code=204)
+    finalize = requests_mock.post(f'http://test/v1/artifacts/{_SHA}/finalize', json={}, status_code=200)
+
+    uploader = _uploader(requests_mock)
+    uploader.submit(Artifact(_BLOB, upload='sync'))
+
+    assert register.called and blob.called and finalize.called
+    assert register.last_request.json()['sha256'] == _SHA  # type: ignore[union-attr]
+    # the direct /blob endpoint requires the write token
+    assert blob.last_request.headers['Authorization'] == 'Bearer write-tok'  # type: ignore[union-attr]
+    assert blob.last_request.body == _BLOB  # type: ignore[union-attr]
+    uploader.shutdown()
+
+
+def test_uploader_dedup_skips_put(requests_mock: requests_mock_module.Mocker) -> None:
+    """When the backend reports the content already exists, no blob is uploaded."""
+    register = requests_mock.post(
+        'http://test/v1/artifacts', json={'sha256': _SHA, 'status': 'exists', 'upload': None}, status_code=201
+    )
+    blob = requests_mock.put(f'http://test/v1/artifacts/{_SHA}/blob', status_code=204)
+
+    uploader = _uploader(requests_mock)
+    uploader.submit(Artifact(_BLOB, upload='sync'))
+
+    assert register.called
+    assert not blob.called
+    uploader.shutdown()
+
+
+def test_uploader_signed_url_omits_auth(requests_mock: requests_mock_module.Mocker) -> None:
+    """A signed object-store URL must be PUT to without the bearer token."""
+    requests_mock.post(
+        'http://test/v1/artifacts',
+        json={
+            'sha256': _SHA,
+            'status': 'upload',
+            'upload': {'method': 'PUT', 'url': 'http://signed.example/put', 'requires_auth': False},
+        },
+        status_code=201,
+    )
+    signed_put = requests_mock.put('http://signed.example/put', status_code=200)
+    requests_mock.post(f'http://test/v1/artifacts/{_SHA}/finalize', json={}, status_code=200)
+
+    uploader = _uploader(requests_mock)
+    uploader.submit(Artifact(_BLOB, upload='sync'))
+
+    assert signed_put.called
+    assert 'Authorization' not in signed_put.last_request.headers  # type: ignore[union-attr]
+    uploader.shutdown()
+
+
+def test_uploader_background_drains_on_flush(requests_mock: requests_mock_module.Mocker) -> None:
+    """A background upload completes once `flush` returns."""
+    register = requests_mock.post(
+        'http://test/v1/artifacts',
+        json={
+            'sha256': _SHA,
+            'status': 'upload',
+            'upload': {'method': 'PUT', 'url': f'http://test/v1/artifacts/{_SHA}/blob', 'requires_auth': True},
+        },
+        status_code=201,
+    )
+    requests_mock.put(f'http://test/v1/artifacts/{_SHA}/blob', status_code=204)
+    finalize = requests_mock.post(f'http://test/v1/artifacts/{_SHA}/finalize', json={}, status_code=200)
+
+    uploader = _uploader(requests_mock)
+    uploader.submit(Artifact(_BLOB, upload='background'))
+    assert uploader.flush(timeout=5) is True
+
+    assert register.called and finalize.called
+    uploader.shutdown()
+
+
+def test_uploader_swallows_errors(requests_mock: requests_mock_module.Mocker) -> None:
+    """A failed upload must never propagate out of `submit` and break the caller."""
+    requests_mock.post('http://test/v1/artifacts', status_code=500)
+
+    uploader = _uploader(requests_mock)
+    uploader.submit(Artifact(_BLOB, upload='sync'))  # must not raise
+    uploader.submit(Artifact(_BLOB, upload='background'))
+    assert uploader.flush(timeout=5) is True
+    uploader.shutdown()
+
+
+def test_uploader_background_drops_when_queue_full(requests_mock: requests_mock_module.Mocker) -> None:
+    """A `background` submit must never block: when the queue is full the artifact is
+    dropped with a warning instead of applying backpressure."""
+    release = threading.Event()
+
+    def slow_register(_request: Any, context: Any) -> dict[str, Any]:
+        # Hold the worker thread so the first artifact stays counted against the budget.
+        release.wait(timeout=5)
+        context.status_code = 201
+        return {'sha256': _SHA, 'status': 'exists', 'upload': None}
+
+    requests_mock.post('http://test/v1/artifacts', json=slow_register)
+
+    # A 1-byte budget: the first (oversized) artifact is admitted since the queue is
+    # empty; while the worker is stuck on it, the second submit overflows and is dropped.
+    uploader = ArtifactUploader(base_url='http://test', token='write-tok', max_queue_bytes=1)
+    uploader.submit(Artifact(_BLOB, upload='background'))
+    with pytest.warns(UserWarning, match='queue is full'):
+        uploader.submit(Artifact(_BLOB, upload='background'))
+
+    release.set()
+    uploader.shutdown()
diff --git a/tests/test_logfire_api.py b/tests/test_logfire_api.py
index 75b8e5fef..8692ce5e1 100644
--- a/tests/test_logfire_api.py
+++ b/tests/test_logfire_api.py
@@ -325,6 +325,13 @@ def func() -> None: ...
     logfire_api.url_from_eval(MagicMock(trace_id='abc', span_id='def'))
     logfire__all__.remove('url_from_eval')
 
+    assert hasattr(logfire_api, 'Artifact')
+    logfire_api.Artifact(b'data', filename='x.bin', content_type='application/octet-stream')
+    logfire__all__.remove('Artifact')
+
+    assert hasattr(logfire_api, 'UploadMode')
+    logfire__all__.remove('UploadMode')
+
     # If it's not empty, it means that some of the __all__ members are not tested.
     assert logfire__all__ == set(), logfire__all__