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.

The options discussed in this article are only available via the API. For more information about getting started with our API, check the guides and interactive reference.

Rate Limiting Videos

One of the main uses of bandwidth rate limiting is for streaming video. This sample configuration can be used to apply a rate limit on different file types:

Adjust Site Scope Configuration

REQUEST

METHOD: PATCH

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/configuration

Request Body:

{
  "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. This sample configuration can be used to apply a rate limit on some audio filetypes:

Adjust Site Scope Configuration

REQUEST

METHOD: PATCH

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/configuration

Request Body:

{
  "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:

Adjust Site Scope Configuration

REQUEST

METHOD: PATCH

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/configuration

Request Body:

{
  "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. We can add some logic with our EdgeRules to add the correct query strings to specific requests:

REQUEST

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/sites/{site_id}/scopes/{scope_id}/rules

Request Body:

{
  "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