---
title: "List sound-effect cues for a table read artifact."
method: GET
path: "/artifacts/{artifactId}/sfx"
tags: ["Artifacts"]
---

# List sound-effect cues for a table read artifact.

`GET /artifacts/{artifactId}/sfx`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/sfx`
- Auth: HTTP bearer

Returns timed sound-effect cues on the read backing this artifact. Scope: `artifact:read`.

## Response `200`

SFX cue list envelope.

- SfxListResponse
  - `sfx` object, required
    - `artifactId` string, required
    - `cues` SfxCue[], required
      - `id` string, required
      - `label` string, required
      - `entryIndex` integer, required
      - `prompt` string, nullable: Sound-effect generation prompt when available.
      - `soundUrl` string, uri, nullable, required
      - `volume` number, nullable
      - `triggerOffset` 'before' | 'with' | 'after': Where the cue fires relative to the target line.
      - `offsetMs` integer: Millisecond timing nudge relative to the trigger placement.
      - `generatedDurationS` number, nullable
      - `isDisabled` boolean: True when the cue is muted/excluded from playback and finalized renders.
      - `enabled` boolean: False when the cue is muted/excluded from playback and finalized renders.
      - `isDraft` boolean, required: True when sound generation has not produced a reusable sound URL yet.
      - `overLine` object, nullable: List only. Set when the cue lands on a spoken line loud enough to cover the words (placed by the read's recording timing when it has one, else a `with` cue over its own line): whose line, how far under the voice its loudest moment sits, and the `suggestedVolume` that keeps the words heard (set it with op: update). Null otherwise, and for an unmeasured, muted or draft cue.
        - `state` 'covers_line', required
        - `entryIndex` integer, required: The spoken line it lands on.
        - `speaker` string, required: That line's character; NARRATOR for narration.
        - `underVoiceDb` number, required: dB its loudest moment sits under the voice (negative: over it).
        - `suggestedVolume` number, required: The volume that puts it back under the words.
        - `sentence` string, required: The plain sentence every surface shows.

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The story artifact does not exist or is owned by another account.
- `409`: The artifact is not in a state where this operation is valid yet (e.g. requesting an MP4 render before the share link exists).
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)