Guides

How to Setup Video or Audio Rate Limiting

Bandwidth rate limiting allows you to set the rate at which files are transferred. This can help with optimizing bandwidth usage on your account and reduce associated costs. For video, or audio streaming, where consumers may decide to abort a download or quit streaming halfway through, this can reduce bandwidth overages.

Rate Limiting Videos

One of the main uses of bandwidth rate limiting is for streaming video. You can configure rate limiting for your videos by updating your site's scope configuration by sending a PATCH request to the Update a scope's configuration endpoint.

The example call below can be used to apply a rate limit on different file types.

curl --request PATCH \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/configuration \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
  "configuration": {
    "bandWidthLimit": {
      "rule": "*:*.mp4,*.mov",
      "values": "ri=50,rs=1200",
      "enabled": true
    }
  }
}

The important key-value pairs to see here are:

  1. rule: This is a string with the form [user-agent-1]:[comma-separated filetypes-1]|[user-agent-2]:[comma-separated filetypes-2]... In our example, we are matching all mp4 and mov files from any requesting user-agent.
  2. values: ri is the number of initial bytes to send at full speed, and rs is the sustained rate in kilobits per second. These values will depend on your use-case, but the sustained rate value should be about 10 percent higher than the bitrate of the video you are streaming.

Rate Limiting Audio

You may also want to stream and rate-limit audio files. You can use the same endpoint to apply a rate limit on some audio filetypes.

curl --request PATCH \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/configuration \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
  "configuration": {
    "bandWidthLimit": {
      "rule": "*:*.mp3,*.ogg,*.opus",
      "values": "ri=40,rs=600",
      "enabled": true
    }
  }
}

The important key-value pairs to see here are:

  1. rule: This is a string with the form [user-agent-1]:[comma-separated filetypes-1]|[user-agent-2]:[comma-separated filetypes-2]... In our example, we are matching all mp3, ogg, and opus files from any requesting user-agent.
  2. values: ri is the number of initial bytes to send at full speed, and rs is the sustained rate in kilobits per second. These values will depend on your use-case, but the sustained rate value should be about 10 percent higher than the bitrate of the video you are streaming.

Rate Limiting with Query Strings

If rate limiting based on user agents and filetypes does not provide enough granularity and control, you can instead apply rate limiting based on query strings.

curl --request PATCH \
     --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/configuration \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
  "configuration": {
    "bandwidthRateLimit": {
      "initialBurstName": "ri",
      "sustainedRateName": "rs",
      "initialBurstUnits": "byte",
      "sustainedRateUnits": "kilobit",
      "enabled": true,
      "methodFilter": "*",
      "pathFilter": "*",
      "headerFilter": "*"
    }
  }
}

This allows for a bit more control, as you can see:

  1. initialBurstName and sustainedRateName: These are the values which should be used in the url for rate-limited requests, ie https://domain.com/video.webp?ri=50&rs=1200
  2. methodFilter, pathFilter, and headerFilter: These are glob pattern-matching strings, which can be used to specify specific subsets of requests which can be rate-limited

As mentioned previously, we recommend setting the sustained rate about 10 percent higher than the bitrate of the video being streamed.

Create Custom EdgeRule on Scope

The available filters are useful, but limited. Additionally (as you may have realized), this relies on query strings in the URL, which are subject to adjustment by end-users, who may remove rate-limiting or adjust it. You can add some logic with our EdgeRules via clientRequestModifications to add the correct query strings to specific requests.

Create an EdgeRule by submitting a POST request to the Create an EdgeRule endpoint.

curl --request POST \
  --url https://gateway.stackpath.com/cdn/v1/stacks/STACK_ID/sites/SITE_ID/scopes/SCOPE_ID/rules \
  --header 'accept: application/json' \
  --header 'authorization: Bearer BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '
{
  "name":"rateLimiter",
  "slug":"rate-limiter",
  "configuration": {
    "clientRequestModification": [
      {
        "urlPattern":"regex:(^https://.*(mp4|mov|webm)$)",
        "urlRewrite":
"%client.request.protocol%://%client.request.host%%client.request.fullFilePath%?ri=50&rs=1200",
        "methodFilter":"GET",
        "headerFilter":"Cookie: *_cookiename=*",
        "enabled":true,
        "flowControl":"break"
      },
      {
        "urlPattern":"regex:(^https://.*(mp4|mov|webm)?[^/]+$)",
        "urlRewrite":
"%client.request.protocol%://%client.request.host%%client.request.fullFilePath%%client.request.params%&ri=50&rs=1200",
        "methodFilter":"GET",
        "headerFilter":"Cookie: *_cookiename=*",
        "enabled":true,
        "flowControl":"break"
      }
    ]
  }
}

This rule is a little bit more complicated than it may need to be, since it is accounting for two different situations. Both of the modifications are checking to make sure that the filetype is mp4, mov, or webm; the request method is GET; and the headers contain a cookie with the name _cookiename. Beyond these requirements:

  1. The first modification checks whether the url ends with mp4, mov, or webm, and appends the query string ?ri=50&rs=1200 if it does.
  2. In case there is already a query string on the url, the second modification checks for that, and then appends the string &ri=50&rs=1200

Updated 30 days ago