Get a Twitch clip

Try in Playground

Retrieve public Twitch clip and playback metadata. Numeric keys group clip information, related clips and viewer data.

GET/v1/twitch/clipx-api-key

Headers

Get your API key

x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters

urlstringrequiredquery

Required HTTPS clips.twitch.tv/<slug> or twitch.tv/<channel>/clip/<slug>. Tracking queries/fragments are removed; credentials, ports and embedded URLs are rejected.

max 2048 chars

Examplehttps://clips.twitch.tv/SyntheticClip

Response fields

104

Primary GraphQL response at 0.data.clip, including extensions and videoURL.

Always included.

0.data.clip.idstring

Public clip ID.

min 1 chars

0.data.clip.slugstring

Clip slug verified against the requested URL.

0.data.clip.urlstring

Always included.

0.data.clip.embedURLstring

Always included.

0.data.clip.titlestring

Always included.

0.data.clip.viewCountinteger

Current source views.

≥ 0

0.data.clip.languagestring

Always included.

0.data.clip.isFeaturedboolean

Always included.

All selected source assets, render states, thumbnail URLs, quality variants and portrait metadata.

up to 20 items

0.data.clip.assets.idstring

Always included.

min 1 chars

0.data.clip.assets.aspectRationumber

Always included.

0.data.clip.assets.typestring

Always included.

0.data.clip.assets.createdAtstring

Always included.

0.data.clip.assets.creationStatestring

Always included.

0.data.clip.assets.curatorobject

Always included.

0.data.clip.assets.thumbnailURLstring

Always included.

0.data.clip.assets.videoQualitiesobject[]

Always included.

up to 20 items

0.data.clip.assets.portraitMetadataJSON

Always included.

0.data.clip.assets.__typenamestring

Always included.

Public clip creator, or null.

0.data.clip.curator.idstring

Always included.

min 1 chars

0.data.clip.curator.loginstring

Always included.

0.data.clip.curator.displayNamestring

Always included.

0.data.clip.curator.__typenamestring

Always included.

0.data.clip.curator.profileImageURLstringnullable

Always included.

Public game metadata, or null.

0.data.clip.game.idstring

Always included.

min 1 chars

0.data.clip.game.slugstring

Always included.

0.data.clip.game.namestring

Always included.

0.data.clip.game.__typenamestring

Always included.

0.data.clip.game.displayNamestring

Always included.

0.data.clip.game.boxArtURLstring

Always included.

Associated broadcast ID and title, or null.

0.data.clip.broadcast.idstring

Always included.

min 1 chars

0.data.clip.broadcast.titlestringnullable

Always included.

0.data.clip.broadcast.__typenamestring

Always included.

Owner profile, partner flag, follower total, stream, last broadcast and logged-out self metadata.

0.data.clip.broadcaster.idstring

Always included.

min 1 chars

0.data.clip.broadcaster.loginstring

Always included.

0.data.clip.broadcaster.displayNamestring

Always included.

0.data.clip.broadcaster.__typenamestring

Always included.

0.data.clip.broadcaster.profileImageURLstringnullable

Always included.

0.data.clip.broadcaster.primaryColorHexstringnullable

Always included.

0.data.clip.broadcaster.isPartnerboolean

Always included.

0.data.clip.broadcaster.followersobject

Always included.

0.data.clip.broadcaster.streamJSON

Always included.

0.data.clip.broadcaster.lastBroadcastJSON

Always included.

0.data.clip.broadcaster.selfJSON

Always included.

0.data.clip.thumbnailURLstring

Always included.

0.data.clip.createdAtstring

Always included.

0.data.clip.isPublishedboolean

Must be true for successful retrieval.

0.data.clip.durationSecondsnumber

Clip duration in seconds.

≥ 0

0.data.clip.champBadgeJSON

Source badge metadata or null.

Expiring public playback signature and JSON value returned by Twitch. They vary by request and are not logged or cached.

0.data.clip.playbackAccessToken.signaturestring

Always included.

min 1 chars

0.data.clip.playbackAccessToken.valuestring

Always included.

min 1 chars

0.data.clip.playbackAccessToken.__typenamestring

Always included.

0.data.clip.videoJSON

Associated video ID/type/title, or null.

0.data.clip.videoOffsetSecondsnumbernullable

Source video offset or null.

Published source media URLs; never downloaded by this worker.

up to 20 items

0.data.clip.videoQualities.sourceURLstring

Always included.

0.data.clip.videoQualities.__typenamestring

Always included.

0.data.clip.isViewerEditRestrictedboolean

Logged-out edit restriction flag. It does not imply that public viewing is restricted.

0.data.clip.suggestedCroppingJSON

Source crop metadata or null.

0.data.clip.__typenamestring

Original GraphQL source type.

0.data.clip.videoURLstring

First video-quality source URL signed with the current public playback signature/token. Expires with that token; request a fresh clip response when needed.

absolute HTTPS URL

Optional.

up to 100 items

0.errors.messagestring

Always included.

Optional.

0.extensions.operationNamestringoptional

Optional.

0.extensions.durationMillisecondsnumberoptional

Optional.

0.extensions.requestIDstringoptional

Optional.

Related-clips GraphQL response. Source errors are retained and produce partial coverage.

1.dataobjectoptional

Optional.

up to 100 items

1.errors.messagestring

Always included.

Optional.

1.extensions.operationNamestringoptional

Optional.

1.extensions.durationMillisecondsnumberoptional

Optional.

1.extensions.requestIDstringoptional

Optional.

Logged-out viewer response; data.user is null. No Twitch account session is used.

2.dataobjectoptional

Optional.

up to 100 items

2.errors.messagestring

Always included.

Optional.

2.extensions.operationNamestringoptional

Optional.

2.extensions.durationMillisecondsnumberoptional

Optional.

2.extensions.requestIDstringoptional

Optional.

requestIdstring

Operation identifier for correlation.

HTTP attempts initiated by this operation, decoded response bytes and elapsed milliseconds. A shared client bootstrap is counted by its initiating operation.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

successboolean

True when the primary requested data is usable.

statusenum

success, partial, failed or challenged. Inspect coverage on HTTP 200.

one of: success, partial

sourceUrlstring

Canonical public Twitch page URL.

absolute HTTPS URL

fetchedAtstring

UTC retrieval timestamp.

Public GraphQL coverage. Clip auxiliary query errors produce partial with auxiliary_graphql_error; missing required primary fields fail.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

up to 2 items

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes

HTTP	failure.code	Meaning
200	`partial`	Primary clip data is usable but a related-clips or viewer GraphQL query returned source errors.
400	`invalid_request`	Missing or unsafe input, unknown parameters, invalid filter/sort, or duplicate parameters.
401	`unauthorized`	Missing or invalid dedicated worker API key.
403	`restricted_page`	Unpublished clip, denied or expired playback token, or unexpected authenticated viewer.
404	`not_found`	The requested channel, video or clip is missing, or the route is unknown.
429	`upstream_rate_limited`	Twitch rate limited retrieval.
502	`upstream_challenged` `public_client_unavailable`	Twitch challenged the request or its public client identifier could not be determined.
502	`upstream_graphql_error` `unsupported_page`	Primary query failure or incomplete, unexpected or mismatched data.
502	`response_too_large` `payload_too_complex`	Byte, depth or JSON node limit exceeded.
502	`unsafe_redirect` `request_limit` `upstream_error`	Bounded transport could not complete.
503	`busy`	All worker admission slots are occupied.
504	`timeout`	The total request deadline expired.

Code example

curl "https://api.scrapeatlas.com/v1/twitch/clip?url=https%3A%2F%2Fclips.twitch.tv%2FSyntheticClip" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.scrapeatlas.com/v1/twitch/clip?url=https%3A%2F%2Fclips.twitch.tv%2FSyntheticClip",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);

const data = await response.json();
console.log(data.status, data);

type Result = {
  status: "success" | "partial" | "failed" | "challenged";
  requestId: string;
  [field: string]: unknown;
};

const response = await fetch(
  "https://api.scrapeatlas.com/v1/twitch/clip?url=https%3A%2F%2Fclips.twitch.tv%2FSyntheticClip",
  {
    headers: {
      "x-api-key": process.env.SCRAPEATLAS_API_KEY!
    }
  }
);

const data = (await response.json()) as Result;
if (data.status === "failed" || data.status === "challenged") {
  throw new Error(`Twitch request failed: ${data.requestId}`);
}
console.log(data);

import requests

response = requests.get(
    "https://api.scrapeatlas.com/v1/twitch/clip",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "url": "https://clips.twitch.tv/SyntheticClip"
    },
    timeout=60,
)
data = response.json()
print(data["status"], data)

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.scrapeatlas.com/v1/twitch/clip?url=https%3A%2F%2Fclips.twitch.tv%2FSyntheticClip", nil)
	req.Header.Set("x-api-key", "YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data["status"], data)
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.scrapeatlas.com/v1/twitch/clip?url=https%3A%2F%2Fclips.twitch.tv%2FSyntheticClip"))
            .GET()
            .header("x-api-key", "YOUR_API_KEY")
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Use your sa_live_… customer key at https://api.scrapeatlas.com.

Responses

Successful result. Synthetic example validated against the runtime contract.

{
  "0": {
    "data": {
      "clip": {
        "id": "4",
        "slug": "SyntheticClip",
        "url": "https://clips.twitch.tv/SyntheticClip",
        "embedURL": "https://clips.twitch.tv/embed?clip=SyntheticClip",
        "title": "Synthetic clip",
        "viewCount": 0,
        "language": "EN",
        "isFeatured": true,
        "assets": [],
        "curator": {
          "id": "1",
          "login": "example",
          "displayName": "Example",
          "profileImageURL": "https://example.test/avatar",
          "primaryColorHex": null,
          "roles": {
            "isPartner": false,
            "__typename": "UserRoles"
          },
          "__typename": "User"
        },
        "game": {
          "id": "2",
          "slug": "example",
          "name": "Example",
          "displayName": "Example",
          "boxArtURL": "https://example.test/game",
          "__typename": "Game"
        },
        "broadcast": {
          "id": "6",
          "title": null,
          "__typename": "Broadcast"
        },
        "broadcaster": {
          "id": "1",
          "login": "example",
          "displayName": "Example",
          "profileImageURL": "https://example.test/avatar",
          "primaryColorHex": null,
          "roles": {
            "isPartner": false,
            "__typename": "UserRoles"
          },
          "__typename": "User",
          "isPartner": false,
          "followers": {
            "totalCount": 0,
            "__typename": "FollowerConnection"
          },
          "stream": null,
          "lastBroadcast": null,
          "self": null
        },
        "thumbnailURL": "https://example.test/thumb",
        "createdAt": "2026-09-10T00:00:00Z",
        "isPublished": true,
        "durationSeconds": 12,
        "champBadge": null,
        "playbackAccessToken": {
          "signature": "synthetic-signature",
          "value": "{\"authorization\": {\"forbidden\": false}, \"expires\": 4102444800, \"clip_slug\": \"SyntheticClip\", \"user_id\": null}",
          "__typename": "PlaybackAccessToken"
        },
        "video": null,
        "videoOffsetSeconds": null,
        "videoQualities": [
          {
            "sourceURL": "https://clips-media-assets2.twitch.tv/example.mp4",
            "__typename": "ClipVideoQuality"
          }
        ],
        "isViewerEditRestricted": true,
        "suggestedCropping": null,
        "__typename": "Clip",
        "videoURL": "https://clips-media-assets2.twitch.tv/example.mp4?sig=synthetic-signature&token=%7B%22authorization%22%3A%20%7B%22forbidden%22%3A%20false%7D%2C%20%22expires%22%3A%204102444800%2C%20%22clip_slug%22%3A%20%22SyntheticClip%22%2C%20%22user_id%22%3A%20null%7D"
      }
    },
    "extensions": {
      "operationName": "ShareClipRenderStatus",
      "durationMilliseconds": 1,
      "requestID": "synthetic-upstream"
    }
  },
  "1": {
    "data": {
      "user": {
        "id": "1",
        "login": "example",
        "clips": {
          "edges": [],
          "pageInfo": {
            "hasNextPage": false,
            "__typename": "PageInfo"
          },
          "__typename": "ClipConnection"
        },
        "__typename": "User"
      }
    },
    "extensions": {
      "operationName": "ClipsCards__User",
      "durationMilliseconds": 1,
      "requestID": "synthetic-related"
    }
  },
  "2": {
    "data": {
      "user": null
    },
    "extensions": {
      "operationName": "GetDisplayName",
      "durationMilliseconds": 1,
      "requestID": "synthetic-upstream"
    }
  },
  "success": true,
  "status": "success",
  "requestId": "00000000-0000-4000-8000-000000000099",
  "sourceUrl": "https://clips.twitch.tv/SyntheticClip",
  "fetchedAt": "2026-09-10T00:00:00.000Z",
  "coverage": {
    "source": "public_graphql",
    "complete": true,
    "warnings": []
  },
  "accounting": {
    "upstreamRequests": 3,
    "responseBytes": 4000,
    "durationMs": 500
  }
}

Missing or unsafe input, unknown parameters, invalid filter/sort, or duplicate parameters.

{
  "requestId": "9d2f1c0a-6b1e-4c7d-9a8e-2f3b4c5d6e7f",
  "accounting": {
    "upstreamRequests": 0,
    "responseBytes": 0,
    "durationMs": 0
  },
  "success": false,
  "status": "failed",
  "failure": {
    "code": "invalid_request",
    "message": "Invalid request: missing, duplicate, unsupported or malformed parameters."
  }
}