Retrieve Event Media

When a camera detects motion or a doorbell is pressed, Seam sends an event that lists the IDs of the media captured for it: usually a short video clip and a thumbnail image. You pass each ID to /media/get to get the media’s status and a short-lived signed URL for downloading or playing it.

Camera event media is in beta. For Arlo and Tapo, Seam turns on camera events and event media for each workspace separately, so contact Seam and ask for them to be turned on for yours. Ring events include media_ids without extra setup. The request and response shapes on this page may change before general availability.

How It Works

Seam creates a camera.activated or device.doorbell_rang event. The event’s media_ids array lists one ID for each piece of media Seam expects for the event.
You call /media/get with a media_id. Seam returns a media object with a status and, once the media is ready, a signed url.
You download or play the media from url right away. The URL expires within minutes, so call /media/get again whenever you need a new one.

Store the media_id, not the url. Signed URLs expire within minutes, while a media ID stays valid for about 30 days. After that, /media/get returns media_not_found for it.

Supported Providers

Provider	Events with media	Where the media comes from	Requirements
Arlo	`camera.activated`	The recording in the Arlo cloud library.	An active Arlo subscription that includes cloud recording.
Ring	`camera.activated`, `device.doorbell_rang`	Ring’s cloud.	An active Ring Protect subscription on the Ring account.
TP-Link Tapo	`camera.activated`	The camera’s microSD card, through the paired Seam Bridge.	The Tapo account password entered in the Connect Webview, a microSD card with recording turned on, and Third-Party Compatibility turned on in the Tapo app.

For Arlo and Tapo, Seam copies the clip into Seam’s private storage and extracts a JPEG thumbnail from it. Seam converts clips to MP4 with H.264 video so that browsers can play them. Ring media stays with Ring: Seam requests a signed URL from Ring each time you call /media/get.

Before You Begin

To retrieve event media, you need:

For Arlo and Tapo, a workspace with camera events and event media turned on. Ring event media doesn’t need to be turned on.
A connected account with a supported camera or doorbell.
A webhook subscribed to camera.activated and, for Ring doorbells, device.doorbell_rang.
An API key, or a client session token that has access to the device.

Step 1: Receive a Camera Event

Subscribe your webhook to camera.activated and device.doorbell_rang. Verify the webhook signature, then store the event’s media_ids along with its event_id and device_id. Example camera.activated event:

{
  "event_id": "0b7f0d6a-5b1e-4d0c-9d5c-2d8f6a3e1c44",
  "event_type": "camera.activated",
  "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
  "device_id": "a83690b2-2b70-409a-9a94-426699b84c97",
  "connected_account_id": "c9d3f2a1-7b4e-4f0a-8e2d-5a6b7c8d9e0f",
  "occurred_at": "2026-09-25T17:03:12.000Z",
  "created_at": "2026-09-25T17:03:12.412Z",
  "activation_reason": "motion_detected",
  "media_ids": [
    "01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f",
    "01a0d985-621c-7c4f-8a3e-5b6c7d8e9f0a"
  ],
  "video_url": "https://connect.getseam.com/media/get?media_id=01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f&format=redirect",
  "image_url": "https://connect.getseam.com/media/get?media_id=01a0d985-621c-7c4f-8a3e-5b6c7d8e9f0a&format=redirect"
}

media_ids doesn’t guarantee any order. Call /media/get for each ID and read media_type to find the clip (video) and the thumbnail (image).
media_ids is missing when Seam isn’t capturing media for the event. For example, event media might not be turned on for an Arlo or Tapo workspace, or the provider might not supply media for that event type.
motion_sub_type (human, vehicle, package, or other) is included when the provider reports it.
video_url and image_url are still included for compatibility. They point to /media/get with format=redirect, and requests to them need the same authentication as any other Seam API request. New integrations should use media_ids.

For Arlo and Tapo, media usually isn’t ready when the event arrives. Seam sends the event first, and then retrieves the recording in the background. Ring media is available as soon as the event arrives.

Step 2: Get the Media

Call /media/get with a media_id. The default format is json, which returns the media object. Request:

const { media } = await seam.media.get({
  media_id: '01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f',
})

console.log(media.status, media.url)

media = seam.media.get(
    media_id="01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f"
)

print(media.status, media.url)

media = seam.media.get(
  media_id: "01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f"
)

puts media.status, media.url

$media = $seam->media->get(
  media_id: "01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f"
);

echo $media->status, $media->url;

var media = seam.Media.Get(
  mediaId: "01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f"
);

Console.WriteLine($"{media.Status} {media.Url}");

var media = seam.media().get(
  MediaGetRequest.builder()
    .mediaId("01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f")
    .build()
);

System.out.println(media.getStatus() + " " + media.getUrl());

# Use GET or POST.
curl -X 'POST' \
  'https://connect.getseam.com/media/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "media_id": "01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f"
}'

Response:

{
  "media": {
    "media_id": "01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f",
    "workspace_id": "398d80b7-3f96-47c2-b85a-6f8ba21d07be",
    "device_id": "a83690b2-2b70-409a-9a94-426699b84c97",
    "event_id": "0b7f0d6a-5b1e-4d0c-9d5c-2d8f6a3e1c44",
    "media_type": "video",
    "content_type": "video/mp4",
    "status": "available",
    "url": "https://media.getseam.com/camera-event-media/...&X-Amz-Signature=...",
    "expires_at": "2026-10-02T17:04:40.000Z",
    "created_at": "2026-09-25T17:03:12.412Z"
  }
}

Media Object

See the media object reference for the complete property list.

Field	Type	Description
`media_id`	string (UUID)	ID of the media.
`workspace_id`	string (UUID)	ID of the workspace that contains the media.
`device_id`	string (UUID) or `null`	ID of the device that captured the media.
`event_id`	string (UUID) or `null`	ID of the event that the media belongs to.
`media_type`	`video` or `image`	Whether the media is a video clip or a still image.
`content_type`	string or `null`	MIME type of the media, such as `video/mp4` or `image/jpeg`.
`status`	`pending`, `available`, `unavailable`, or `failed`	See Media Statuses.
`url`	string or `null`	Short-lived signed URL from which you can download the media. `null` unless `status` is `available`. The URL expires within minutes.
`expires_at`	string (date-time) or `null`	When the media itself stops being available. This is not when `url` expires. `null` when Seam doesn’t know when the media expires, as for Ring media.
`created_at`	string (date-time)	When the media was created.

The response has no field for when url expires, and the lifetime varies by provider. Treat every URL as valid for only a few minutes, and call /media/get again for a new one rather than caching it.

Media Statuses

`status`	Meaning	`url`	What to do
`pending`	Seam is still retrieving the media from the provider.	`null`	Call `/media/get` again later. See Step 3.
`available`	The media is ready.	A signed URL	Download or play it right away.
`unavailable`	No recording exists or can be retrieved for the event. For example, the provider has no matching recording (for Arlo, Seam waits about three minutes for one), the Tapo camera was connected without the Tapo account password, or the camera is no longer connected.	`null`	Stop retrying.
`failed`	Seam couldn’t retrieve, convert, or store the media, including when the media was still `pending` after Seam’s last retry.	`null`	Stop retrying.

pending is the only status that changes. After the media’s expires_at passes, /media/get returns a media_not_available error for it. About 30 days after the event, Seam deletes the media record entirely, and /media/get returns media_not_found.

Step 3: Wait for Pending Media

Seam can’t retrieve an Arlo or Tapo recording until the provider finishes it, so media often stays pending for a minute or more after the event. Seam doesn’t send an event when media becomes available, so poll /media/get with backoff:

Wait about 15 seconds after the event before the first request.
Double the delay after each pending response, up to 30 seconds between requests.
Stop after about 10 minutes and treat the media as unavailable.
Poll from a background job, not from the webhook handler. Return a 2xx from the webhook handler as soon as you store the event.

JavaScript

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function waitForMedia(seam, media_id) {
  const deadline = Date.now() + 10 * 60 * 1000
  let delay_ms = 15_000

  while (Date.now() < deadline) {
    await sleep(delay_ms)
    const { media } = await seam.media.get({ media_id })
    if (media.status !== 'pending') return media
    delay_ms = Math.min(delay_ms * 2, 30_000)
  }

  return null
}

Step 4: Use the Signed URL

The url is a signed, short-lived link to the media file. It expires within minutes, and the exact lifetime varies by provider. The response doesn’t say when: expires_at is when the media itself stops being available, not when the URL expires.

Don’t store the URL. Store the media_id and call /media/get when you need a URL.
Request a new URL when playback fails. A video player can request byte ranges from the URL long after the page loads, for example when the user seeks. If the player reports an error, call /media/get again and set the new URL as the source.
Keep the URL private. Anyone who has the URL can download the media until it expires. Don’t log it or put it in analytics events.
Keep your own copy if you need it longer. Seam keeps stored Arlo and Tapo media for 7 days, and expires_at tells you when. After that, /media/get returns media_not_available. Ring media has no expires_at: it’s available for up to 30 days, subject to the retention of the Ring account’s Ring Protect plan.

JSON vs. Redirect

/media/get accepts a format parameter:

`format`	Response	Use it when
`json` (default)	`200` with the `media` object.	You want to check `status` or `expires_at`, or set the `src` of an `<img>` or `<video>` element in a browser.
`redirect`	`302` to the signed URL.	A server-side client downloads the file and follows redirects, such as `curl -L`.

Browsers can’t add an Authorization header to an <img> or <video> element’s request, so you can’t point one straight at /media/get. In a browser, request the JSON format with your client session token, then set the returned url as the element’s src. This works for media that Seam stores, such as Arlo clips:

JavaScript

const response = await fetch('https://connect.getseam.com/media/get', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'seam-client-session-token': clientSessionToken,
  },
  body: JSON.stringify({ media_id: mediaId }),
})
const { media } = await response.json()

if (media.status === 'available') {
  document.querySelector('video').src = media.url
}

To download a clip on a server:

cURL

curl -L -o clip.mp4 \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  'https://connect.getseam.com/media/get?media_id=01a0d985-621c-7b3e-9f2d-4a5b6c7d8e9f&format=redirect'

Ring video URLs may not play directly in a browser <video> element. When a Ring clip is shorter than the window Seam requests, Ring’s servers answer with a partial-content response that browsers reject. For Ring clips, download the file on your server and serve it to the browser yourself.

If the media isn’t available yet, the redirect format returns an error instead of a 302. See Errors.

Authorization

/media/get accepts the same credentials as other Seam read endpoints: an API key, a personal access token with a workspace, or a client session token. A client session can only get media for the devices it has access to. That is, devices in the connected accounts, Connect Webviews, or user identity that you associated with the client session when you created it, or, for a client session created with a customer_key, that customer’s devices. For any other device’s media, Seam returns media_not_found, the same error it returns for an ID that doesn’t exist, so a client can’t probe for media in other accounts. Use client sessions to show media in your users’ browsers or mobile apps without exposing your API key.

Errors

HTTP status	`error.type`	Cause
`404`	`media_not_found`	The `media_id` doesn’t exist in this workspace, Seam has deleted it, or your credentials don’t give access to the device that captured it.
`404`	`media_not_available`	Seam has no URL for the media. With `format=redirect`, this happens whenever the media isn’t `available`, so use `format=json` to read its status. With either format, it also happens when the media’s `expires_at` has passed, or when the provider can’t return a URL, for example for a Ring account without an active Ring Protect subscription.

Provider Notes

TP-Link Tapo

Seam retrieves the clip from the camera’s microSD card through the paired Seam Bridge, so the Bridge and the camera must stay online after the event.
Seam needs the Tapo account password, which is the password for the Tapo app, not the Camera Account password. Enter it in the optional Tapo account password field of the Connect Webview. For a camera connected without it, media ends up unavailable. To add it, reconnect the camera. Recordings start with the next motion event. See Tapo event recordings.
Without a microSD card, or when the card has no recording that contains the event, the media ends up unavailable.
The sandbox Tapo camera has no microSD recordings.

Arlo

Seam retrieves the clip from the Arlo cloud library. Without a subscription that includes cloud recording, Arlo stores no recording, and the media ends up unavailable.
Arlo clips are often recorded in HEVC. Seam converts them to H.264 so that browsers can play them.

Ring

Ring media is available for both camera.activated and device.doorbell_rang events.
Ring only keeps clips for accounts with an active Ring Protect subscription.
Seam requests a new signed URL from Ring on each /media/get call. Ring media is available as soon as the event arrives, and its expires_at is null. If Ring no longer has the recording, /media/get returns media_not_available.
Ring video URLs may not play directly in a browser. See JSON vs. Redirect.

Next Steps

Get Media: Full request and response reference for /media/get.
Stream live video: Watch a camera’s live feed in the browser over WebRTC.
Webhooks: Receive and verify camera events.
Client session tokens: Give your users’ browsers scoped access to their devices.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Retrieve Event Media

How It Works

Supported Providers

Before You Begin

Step 1: Receive a Camera Event

Step 2: Get the Media

Media Object

Media Statuses

Step 3: Wait for Pending Media

Step 4: Use the Signed URL

JSON vs. Redirect

Authorization

Errors

Provider Notes

TP-Link Tapo

Arlo

Ring

Next Steps

​How It Works

​Supported Providers

​Before You Begin

​Step 1: Receive a Camera Event

​Step 2: Get the Media

​Media Object

​Media Statuses

​Step 3: Wait for Pending Media

​Step 4: Use the Signed URL

​JSON vs. Redirect

​Authorization

​Errors

​Provider Notes

​TP-Link Tapo

​Arlo

​Ring

​Next Steps

How It Works

Supported Providers

Before You Begin

Step 1: Receive a Camera Event

Step 2: Get the Media

Media Object

Media Statuses

Step 3: Wait for Pending Media

Step 4: Use the Signed URL

JSON vs. Redirect

Authorization

Errors

Provider Notes

TP-Link Tapo

Arlo

Ring

Next Steps