EdgeWorkers API v1

Execute JavaScript at the edge to optimize performance and customize web experiences.

Learn more:


Overview

The EdgeWorkers service lets you run JavaScript at the edge of the Internet to dynamically manage web traffic. You can use the EdgeWorkers API to deploy custom code on thousands of Akamai edge servers and apply logic that creates powerful web experiences.

Use the EdgeWorkers service to:

  • Redirect requests based on geography, device, and user-agent.

  • Apply conditional logic to filter requests and construct responses.

  • Customize error responses to improve web experiences, even when the origin is down.

  • Add or remove debug information from HTTP responses.

Get started

To use this API for the first time:

  • Confirm that you have the entitlement for the EdgeWorkers service in your contract. See Limitations in the EdgeWorkers User Guide for a list of supported delivery products.

  • Review Get Started with APIs for instructions on setting up authentication tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net. To enable this API, select the API service named EdgeWorkers, and choose READ-WRITE as the access level.

  • Add a rule in Property Manager to enable the EdgeWorkers behavior. Follow the instructions in the User Guide

EdgeWorkers bundle format

To create the EdgeWorkers bundle, you need a JavaScript source file called main.js that contains event handler definitions for when to execute the code:

  • onClientRequest. This event happens for every request as the request is received, before checking if a response is available in cache.

  • onOriginRequest. This event happens just before sending the request to the origin.

  • onOriginResponse. This event happens as the origin response is created.

  • onClientResponse. This event happens for every request just before the client response is sent.

  • responseProvider. This event happens for every request before the client response is sent. It lets you generate and manipulate response bodies within an EdgeWorkers function.

You also need to create a manifest file called bundle.json that includes meta information as described in the table below.

Name Type Description Required
edgeworker-version String Unique identifier for the EdgeWorkers version.
bundle-version Integer Bundle format version.
api-version String Version of JavaScript API when the EdgeWorkers code was created.
description String Phrase describing the EdgeWorkers script function.
misc Object Information you can include in the manifest to identify the EdgeWorkers function.

NOTE: For edgeworker-version limit characters to alphanumeric, underscore, dash, dot, and tilde.

{
    "edgeworker-version":"4.22.3",
    "bundle-version":1,
    "api-version":"0.3",
    "description":"Language Redirect",
    "misc":{
        "author":"jsmith",
        "git-commit":"4ce52c8ff4fdd1771e5347297ea5691b55c4f6ed",
        "updated":"2027-09-23"
    }
}

Validation error types

This table provides details for each validation error type.

Error type Description
EMPTY_TARBALL The EdgeWorkers code bundle is empty. Update the code bundle and upload it again.
INVALID_GZIP_FORMAT The GZIP format of the EdgeWorkers code bundle is invalid. Review the code bundle for errors and upload it again.
INVALID_MANIFEST The EdgeWorkers code bundle contains an invalid manifest file. Review the code bundle for errors and upload it again.
INVALID_TAR_ARCHIVE The TAR archive of the EdgeWorkers code bundle is invalid. Review the code bundle for errors and upload it again.
MAX_COMPRESSED_SIZE_EXCEEDED The compressed size of the EdgeWorkers code bundle is invalid. Review the code bundle for errors and upload it again.
MAX_UNCOMPRESSED_SIZE_EXCEEDED The GZIP format of the EdgeWorkers code bundle is invalid. Review the code bundle for errors and upload it again.
MISSING_MANDATORY_FILES The EdgeWorkers code bundle is missing mandatory files. Review the contents of the code bundle and upload it again.
STATIC_VALIDATION_FAILED The EdgeWorkers code bundle failed static validation. Review the code bundle for errors and upload it again.

Resource limiting

This API imposes limits on some of the resources you can deploy. See Limitations in the EdgeWorkers User Guide.

Resources

Here are some terms and concepts that will help you understand how to use this API.

  • ID: The EdgeWorkers API generates a unique edgeWorkerId, a numeric identifier that enables you to activate and manage your EdgeWorkers scripts.

  • Group: Contains information about what EdgeWorker capabilities and permissions are allowed within the group.

  • Version: A unique string value that enables you to track revision history for an edgeWorkerId. Each version refers to a specific bundle that contains your EdgeWorker script.

  • Activation: EdgeWorkers code, identified by edgeWorkerId+version, set to execute on the Akamai staging or production network.

  • Script Bundle: A collection of files including main.js, the JavaScript source that contains event handler functions, and bundle.json packaged together in a compressed .tgz file. See EdgeWorkers bundle format for details.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Groups  
List permission groups GET /edgeworkers/v1/groups
Get a permission group GET /edgeworkers/v1/groups/{groupId}
Contracts  
List contract IDs GET /edgeworkers/v1/contracts
Resource tiers  
List resource tiers GET /edgeworkers/v1/resource-tiers{?contractId}
EdgeWorker IDs  
List EdgeWorker IDs GET /edgeworkers/v1/ids{?groupId,resourceTierId}
Create a new EdgeWorker ID POST /edgeworkers/v1/ids
Get an EdgeWorker GET /edgeworkers/v1/ids/{edgeWorkerId}
Update an EdgeWorker PUT /edgeworkers/v1/ids/{edgeWorkerId}
Clone an EdgeWorker ID POST /edgeworkers/v1/ids/{edgeWorkerId}/clone
Get the resource tier GET /edgeworkers/v1/ids/{edgeWorkerId}/resource-tier
Validations  
Validate an EdgeWorkers code bundle POST /edgeworkers/v1/validations
Versions  
List versions GET /edgeworkers/v1/ids/{edgeWorkerId}/versions
Create a new version POST /edgeworkers/v1/ids/{edgeWorkerId}/versions
Get version details GET /edgeworkers/v1/ids/{edgeWorkerId}/versions/{version}
Download an EdgeWorker bundle GET /edgeworkers/v1/ids/{edgeWorkerId}/versions/{version}/content
Activations  
List activations GET /edgeworkers/v1/ids/{edgeWorkerId}/activations{?version}
Activate an EdgeWorker version POST /edgeworkers/v1/ids/{edgeWorkerId}/activations
Get an activation GET /edgeworkers/v1/ids/{edgeWorkerId}/activations/{activationId}
Deactivations  
List deactivations GET /edgeworkers/v1/ids/{edgeWorkerId}/deactivations{?version}
Deactivate an EdgeWorker version POST /edgeworkers/v1/ids/{edgeWorkerId}/deactivations
Get a deactivation GET /edgeworkers/v1/ids/{edgeWorkerId}/deactivations/{deactivationId}
Reports  
List reports GET /edgeworkers/v1/reports
Get an EdgeWorker report GET /edgeworkers/v1/reports/{reportId}{?start,edgeWorker,end,status,eventHandler}
Secure Token  
Get a secure token GET /edgeworkers/v1/secure-token/{propertyId}{?acl,url,expiry,network}

List permission groups

View a list of groups and the associated permission capabilities, for example: activate a version or fetch an EdgeWorker ID.

GET /edgeworkers/v1/groups

Status 200 application/json

Object type: Permissions

Download schema: groups.json

Response body:

{
    "groups": [
        {
            "groupId": 4284,
            "groupName": "Group #42",
            "capabilities": [
                "VIEW",
                "VIEW_VERSION",
                "VIEW_ACTIVATION",
                "ACTIVATE"
            ]
        },
        {
            "groupId": 109795,
            "groupName": "ESSL Behavior Tests",
            "capabilities": [
                "VIEW",
                "EDIT",
                "VIEW_VERSION",
                "CREATE_VERSION",
                "VIEW_ACTIVATION",
                "ACTIVATE"
            ]
        }
    ]
}

Get a permission group

View details on the capabilities enabled within a specified group, for example: activate a version or fetch an EdgeWorker ID.

GET /edgeworkers/v1/groups/{groupId}

Sample: /edgeworkers/v1/groups/109795

Parameter Type Sample Description
URL path parameters
groupId Number 109795 Unique identifier for an EdgeWorker group. You can pass in plain integer IDs, or add a grp_ prefix. The Property Manager API supports both formats. See ID prefixes for details.

Status 200 application/json

Object type: Permissions

Download schema: group.json

Response body:

{
    "groupId": 109795,
    "groupName": "ESSL Behavior Tests",
    "capabilities": [
        "VIEW",
        "VIEW_VERSION",
        "VIEW_ACTIVATION"
    ]
}
  1. Run the List groups operation.

  2. Select a groupId from the Permissions response object, then make a GET request to /edgeworkers/v1/groups/{groupId}.

List contract IDs

View the list of contract IDs that you can use to list resource tiers.

GET /edgeworkers/v1/contracts

Status 200 application/json

Object type: Contract

Download schema: contract-ids.json

Response body:

{
    "contractIds": [
        "1-599K",
        "B-M-28QYF3M"
    ]
}

List resource tiers

View the list of available resource tiers for a specific contract ID. The resource tier defines the resource consumption limits for an EdgeWorker ID.

GET /edgeworkers/v1/resource-tiers{?contractId}

Sample: /edgeworkers/v1/resource-tiers?contractId=M–28TSXXX

Parameter Type Sample Description
Required query parameters
contractId String M-28TSXXX Unique identifier of a contract.

Status 200 application/json

Object type: ResourceTier

Download schema: resource-tiers.json

Response body:

{
    "resourceTiers": [
        {
            "resourceTierId": 100,
            "resourceTierName": "Basic Compute",
            "edgeWorkerLimits": [
                {
                    "limitName": "Maximum CPU time during initialization",
                    "limitValue": 30,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time during initialization",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel per EdgeWorker ID",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum memory usage per event handler",
                    "limitValue": 1310720,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time per event handler",
                    "limitValue": 10,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time per event handler",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed from a parent request",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel with the parent request",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time per HTTP sub-request",
                    "limitValue": 0,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size per HTTP sub-request",
                    "limitValue": 0,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum memory usage for responseProvider",
                    "limitValue": 2097152,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time for responseProvider",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time for responseProvider",
                    "limitValue": 4000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed for responseProvider",
                    "limitValue": 50,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel for responseProvider",
                    "limitValue": 5,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time for HTTP sub-requests during the execution of the responseProvider event handler",
                    "limitValue": 1000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size for HTTP sub-requests during the responseProvider event handler",
                    "limitValue": 1048576,
                    "limitUnit": "BYTE"
                }
            ]
        },
        {
            "resourceTierId": 200,
            "resourceTierName": "Dynamic Compute",
            "edgeWorkerLimits": [
                {
                    "limitName": "Maximum CPU time during initialization",
                    "limitValue": 30,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time during initialization",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel per EdgeWorker ID",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum memory usage per event handler",
                    "limitValue": 1310720,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time per event handler",
                    "limitValue": 50,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time per event handler",
                    "limitValue": 4000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed from a parent request",
                    "limitValue": 1,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel with the parent request",
                    "limitValue": 1,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time per HTTP sub-request",
                    "limitValue": 1000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size per HTTP sub-request",
                    "limitValue": 1048576,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum memory usage for responseProvider",
                    "limitValue": 2097152,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time for responseProvider",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time for responseProvider",
                    "limitValue": 4000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed for responseProvider",
                    "limitValue": 50,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel for responseProvider",
                    "limitValue": 5,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time for HTTP sub-requests during the execution of the responseProvider event handler",
                    "limitValue": 1000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size for HTTP sub-requests during the execution of the responseProvider event handler",
                    "limitValue": 1048576,
                    "limitUnit": "BYTE"
                }
            ]
        }
    ]
}
  1. Run the List contract IDs operation and select the relevant contractId.

  2. Make a GET request to /edgeworkers/v1/resource-tiers{?contractId}.

List EdgeWorker IDs

View the list of EdgeWorkers in the identified group.

GET /edgeworkers/v1/ids{?groupId,resourceTierId}

Sample: /edgeworkers/v1/ids?groupId=72297&resourceTierId=200

Parameter Type Sample Description
Optional query parameters
groupId Integer 72297 Unique identifier for the Akamai group containing the EdgeWorker.
resourceTierId Integer 200 Unique identifier of the resource tier.

Status 200 application/json

Object type: EdgeWorker

Download schema: ids.json

Response body:

{
    "edgeWorkerIds": [
        {
            "edgeWorkerId": 1,
            "name": "Ew_1",
            "resourceTierId": 100,
            "accountId": "B-M-1KQK3WU",
            "groupId": 72297,
            "createdBy": "jsmith",
            "createdTime": "2018-10-15T14:49:40Z",
            "lastModifiedBy": "jsmith",
            "lastModifiedTime": "2018-10-15T15:21:15Z"
        },
        {
            "edgeWorkerId": 2,
            "name": "EdgeWorker #2",
            "resourceTierId": 200,
            "accountId": "B-M-1KQK3WU",
            "groupId": 72297,
            "createdBy": "jsmith",
            "createdTime": "2018-10-15T16:54:40Z",
            "lastModifiedBy": "jsmith",
            "lastModifiedTime": "2018-10-15T16:54:40Z"
        }
    ]
}
  1. Run the List groups operation.

  2. Make a GET request to /edgeworkers/v1/ids.

  3. If you want to list EdgeWorker IDs for a specific group, select a groupId from the Permissions response object, then make a GET request to /edgeworkers/v1/ids{?groupId}.

  4. If you want to list EdgeWorker IDs for a specific resource tier, select a resourceTierId from the Resource tier response object, then make a GET request to /edgeworkers/v1/ids{?resourceTierId}.

  5. The operation responds with the EdgeWorker object.

Create a new EdgeWorker ID

Register a new EdgeWorker within a particular group.

POST /edgeworkers/v1/ids

Content-Type: application/json

Object type: EdgeWorker

Download schema: ids-post-request.json

Request body:

{
    "groupId": 72297,
    "name": "Ew_42",
    "resourceTierId": 100
}

Status 201 application/json

Headers:

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42

Object type: EdgeWorker

Download schema: id.json

Response body:

{
    "edgeWorkerId": 42,
    "name": "Ew_42",
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "resourceTierId": 200,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}
  1. Run the Get a group operation to get the groupId assigned to the EdgeWorker.

  2. Create a JSON request body that includes the groupId, a name, and a resourceTierId.

  3. POST the object to /edgeworkers/v1/ids.

  4. Optionally store the Location response header, which tells you where to GET the new EdgeWorker ID from.

  5. View the response EdgeWorker object for details on the registered EdgeWorker.

Get an EdgeWorker

View details for a specific EdgeWorker.

GET /edgeworkers/v1/ids/{edgeWorkerId}

Sample: /edgeworkers/v1/ids/42

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier of the EdgeWorker.

Status 200 application/json

Object type: EdgeWorker

Download schema: id.json

Response body:

{
    "edgeWorkerId": 42,
    "name": "Ew_1",
    "resourceTierId": 200,
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}
  1. Run the List EdgeWorker IDs operation.

  2. Select an edgeWorkerId from the EdgeWorker members response object, then make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}.

Update an EdgeWorker

Update the name or groupId of an existing EdgeWorker.

PUT /edgeworkers/v1/ids/{edgeWorkerId}

Sample: /edgeworkers/v1/ids/42

Content-Type: application/json

Object type: EdgeWorker

Download schema: id-put-request.json

Request body:

{
    "groupId": 123456,
    "name": "New EdgeWorker Name"
}
Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier of the EdgeWorker.

Status 200 application/json

Object type: EdgeWorker

Download schema: id.json

Response body:

{
    "edgeWorkerId": 42,
    "name": "New EdgeWorker Name",
    "resourceTierId": 200,
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}
  1. Run the List EdgeWorker IDs operation.

  2. Select an edgeWorkerId from the EdgeWorker members response object, then make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}.

  3. Modify the name of the EdgeWorker in the response using this syntax "name": "New EdgeWorker Name".

  4. PUT the object to /edgeworkers/v1/ids/{edgeWorkerId}.

Clone an EdgeWorker ID

Clone an EdgeWorker ID to change the resource tier.

POST /edgeworkers/v1/ids/{edgeWorkerId}/clone

Sample: /edgeworkers/v1/ids/42/clone

Content-Type: application/json

Object type: EdgeWorker

Download schema: ids-clone-request.json

Request body:

{
    "groupId": 72297,
    "name": "Ew_42",
    "resourceTierId": 200
}
Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier of the EdgeWorker.

Status 201 application/json

Headers:

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/43

Object type: EdgeWorker

Download schema: id.json

Response body:

{
    "edgeWorkerId": 43,
    "name": "Ew_42",
    "accountId": "B-M-1KQK3WU",
    "groupId": 72297,
    "resourceTierId": 100,
    "sourceEdgeWorkerId": 42,
    "createdBy": "jsmith",
    "createdTime": "2018-10-15T14:49:40Z",
    "lastModifiedBy": "jsmith",
    "lastModifiedTime": "2018-10-15T15:21:15Z"
}

Get the resource tier

View the details of the resource tier assigned to the EdgeWorker ID.

GET /edgeworkers/v1/ids/{edgeWorkerId}/resource-tier

Sample: /edgeworkers/v1/ids/42/resource-tier

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier of the EdgeWorker.

Status 200 application/json

Object type: ResourceTier

Download schema: resource-tier.json

Response body:

{
    "resourceTierId": 200,
    "resourceTierName": "Dynamic Compute",
    "edgeWorkerLimits": [
        {
            "limitName": "Maximum CPU time during initialization",
            "limitValue": 30,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum wall time during initialization",
            "limitValue": 100,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum number of HTTP sub-requests allowed in parallel per EdgeWorker ID",
            "limitValue": 0,
            "limitUnit": "COUNT"
        },
        {
            "limitName": "Maximum memory usage per event handler",
            "limitValue": 1310720,
            "limitUnit": "BYTE"
        },
        {
            "limitName": "Maximum CPU time per event handler",
            "limitValue": 50,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum wall time per event handler",
            "limitValue": 4000,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum number of HTTP sub-requests allowed from a parent request",
            "limitValue": 1,
            "limitUnit": "COUNT"
        },
        {
            "limitName": "Maximum number of HTTP sub-requests allowed in parallel with the parent request",
            "limitValue": 1,
            "limitUnit": "COUNT"
        },
        {
            "limitName": "Maximum wall time per HTTP sub-request",
            "limitValue": 1000,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum response size per HTTP sub-request",
            "limitValue": 1048576,
            "limitUnit": "BYTE"
        },
        {
            "limitName": "Maximum memory usage for responseProvider",
            "limitValue": 2097152,
            "limitUnit": "BYTE"
        },
        {
            "limitName": "Maximum CPU time for responseProvider",
            "limitValue": 100,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum wall time for responseProvider",
            "limitValue": 4000,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum number of HTTP sub-requests allowed for responseProvider",
            "limitValue": 50,
            "limitUnit": "COUNT"
        },
        {
            "limitName": "Maximum number of HTTP sub-requests allowed in parallel for responseProvider",
            "limitValue": 5,
            "limitUnit": "COUNT"
        },
        {
            "limitName": "Maximum walltime for HTTP sub-requests during the execution of the responseProvider event handler",
            "limitValue": 1000,
            "limitUnit": "MILLISECOND"
        },
        {
            "limitName": "Maximum response size for HTTP sub-requests during the responseProvider event handler",
            "limitValue": 1048576,
            "limitUnit": "BYTE"
        }
    ]
}

Validate an EdgeWorker code bundle

Return a list of errors containing details on how to fix your code bundle. See Validation error types.

POST /edgeworkers/v1/validations

Content-Type: application/gzip

Request body:

(Body specifies GZIP binary data.)

Status 200 application/json

Object type: Validation

Download schema: validation.json

Response body:

{
    "errors": [
        {
            "type": "STATIC_VALIDATION_FAILED",
            "message": "static validation failed : main.js::9:16 SyntaxError: Unexpected identifier."
        },
        {
            "type": "INVALID_MANIFEST",
            "message": "manifest file is invalid"
        }
    ]
}

List versions

View a list of EdgeWorker versions.

GET /edgeworkers/v1/ids/{edgeWorkerId}/versions

Sample: /edgeworkers/v1/ids/42/versions

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.

Status 200 application/json

Object type: Version

Download schema: versions.json

Response body:

{
    "versions": [
        {
            "edgeWorkerId": 42,
            "version": 1,
            "accountId": "B-M-1KQK3WU",
            "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
            "createdBy": "jsmith",
            "createdTime": "2018-07-05T18:17:46Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 2,
            "accountId": "B-M-1KQK3WU",
            "checksum": "8277e0910d750195b448797616e091ad616e091a",
            "createdBy": "jsmith",
            "createdTime": "2018-07-05T23:01:34Z"
        }
    ]
}
  1. Run the List EdgeWorker IDs operation.

  2. Select an edgeWorkerId from the EdgeWorker members response object, then make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/versions.

  3. The operation responds with the Version objects.

Create a new version

Create a new version of an EdgeWorker.

POST /edgeworkers/v1/ids/{edgeWorkerId}/versions

Sample: /edgeworkers/v1/ids/42/versions

Content-Type: application/gzip

Request body:

(Body specifies GZIP binary data.)
Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.

Status 201 application/json

Headers:

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42/versions/5

Object type: Version

Download schema: version.json

Response body:

{
    "edgeWorkerId": 42,
    "version": 5,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-05T18:17:46Z"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker response object.

  2. Build the script bundle, specifying the edgeworker-version as described in EdgeWorkers bundle format.

  3. POST the script bundle to /edgeworkers/v1/ids/{edgeWorkerId}/versions.

  4. Optionally store the Location response header, which tells you where to GET the new version from.

  5. The operation responds with a Version object, which reflects the new version.

Get version details

View details for a specific version.

GET /edgeworkers/v1/ids/{edgeWorkerId}/versions/{version}

Sample: /edgeworkers/v1/ids/42/versions/2.3.0

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.
version String 2.3.0 Unique identifier for an EdgeWorker version.

Status 200 application/json

Object type: Version

Download schema: version.json

Response body:

{
    "edgeWorkerId": 42,
    "version": 3,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-09T21:51:07Z"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Run the List versions operation and select a version from the Version members response object.

  3. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/versions/{version}.

Download an EdgeWorker bundle

Download the bundle containing the code the EdgeWorker executes.

GET /edgeworkers/v1/ids/{edgeWorkerId}/versions/{version}/content

Sample: /edgeworkers/v1/ids/42/versions/2.3.0/content

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.
version String 2.3.0 Unique identifier for an EdgeWorker version.

Status 200 application/gzip

Response body:

(Body specifies GZIP binary data.)
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Run the List versions operation and select a version from the Version members response object.

  3. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/versions/{version}/content.

  4. Open the downloaded file to see the JavaScript code for the EdgeWorker.

List activations

View the list of activations for an existing EdgeWorker based on ID. You can choose to specify the version in the request.

GET /edgeworkers/v1/ids/{edgeWorkerId}/activations{?version}

Sample: /edgeworkers/v1/ids/42/activations?version=5

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.
Optional query parameters
version String 5 Unique identifier for a specific EdgeWorker version.

Status 200 application/json

Object type: Activation

Download schema: activations.json

Response body:

{
    "activations": [
        {
            "edgeWorkerId": 42,
            "version": 2,
            "activationId": 3,
            "accountId": "B-M-1KQK3WU",
            "status": "PENDING",
            "network": "PRODUCTION",
            "createdBy": "jdoe",
            "createdTime": "2018-07-09T09:03:28Z",
            "lastModifiedTime": "2018-07-09T09:04:42Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 1,
            "activationId": 1,
            "accountId": "B-M-1KQK3WU",
            "status": "IN_PROGRESS",
            "network": "STAGING",
            "createdBy": "jsmith",
            "createdTime": "2018-07-09T08:13:54Z",
            "lastModifiedTime": "2018-07-09T08:35:02Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 2,
            "activationId": 2,
            "accountId": "B-M-1KQK3WU",
            "status": "COMPLETE",
            "network": "PRODUCTION",
            "createdBy": "asmith",
            "createdTime": "2018-07-10T14:23:42Z",
            "lastModifiedTime": "2018-07-10T14:53:25Z"
        }
    ]
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Run the List versions operation and select a version from the Version members response object.

  3. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/activations{?version}.

  4. View the response body for details on the Activation.

Activate an EdgeWorker version

Activate an existing EdgeWorker version on the Akamai network, either staging or production.

POST /edgeworkers/v1/ids/{edgeWorkerId}/activations

Sample: /edgeworkers/v1/ids/42/activations

Content-Type: application/json

Object type: Activation

Download schema: activations-post-request.json

Request body:

{
    "network": "PRODUCTION",
    "version": "2"
}
Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.

Status 201 application/json

Headers:

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42/activations/3

Object type: Activation

Download schema: activation.json

Response body:

{
    "edgeWorkerId": 42,
    "version": 5,
    "activationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PRESUBMIT",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2019-04-05T18:17:46Z",
    "lastModifiedTime": "2019-04-05T18:17:46Z"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Build a JSON request object specifying the version you want to activate and the network on which to activate the EdgeWorker.

  3. POST the object to /edgeworkers/v1/ids/{edgeWorkerId}/activations.

  4. Optionally store the Location response header, which tells you where to GET the new activation from.

  5. View the response body for details on the Activation.

Get an activation

View details for a specific activation.

GET /edgeworkers/v1/ids/{edgeWorkerId}/activations/{activationId}

Sample: /edgeworkers/v1/ids/42/activations/3

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.
activationId Integer 3 Unique identifier for an EdgeWorker activation.

Status 200 application/json

Object type: Activation

Download schema: activation.json

Response body:

{
    "edgeWorkerId": 42,
    "version": 9,
    "activationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PENDING",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2018-08-04T11:42:56Z",
    "lastModifiedTime": "2018-08-04T12:00:03Z"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Run the List activations operation and select an activationId from the Activation members response object.

  3. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/activations/{activationId}.

List deactivations

View the list of deactivations for an existing EdgeWorker. You can limit the results to a specific version.

GET /edgeworkers/v1/ids/{edgeWorkerId}/deactivations{?version}

Sample: /edgeworkers/v1/ids/42/deactivations?version=5

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.
Optional query parameters
version String 5 Unique identifier for a specific EdgeWorker version.

Status 200 application/json

Object type: Deactivation

Download schema: deactivations.json

Response body:

{
    "deactivations": [
        {
            "edgeWorkerId": 42,
            "version": 2,
            "deactivationId": 3,
            "accountId": "B-M-1KQK3WU",
            "status": "PENDING",
            "network": "PRODUCTION",
            "note": "EdgeWorker ID 42 is no longer used in production.",
            "createdBy": "jdoe",
            "createdTime": "2018-07-09T09:03:28Z",
            "lastModifiedTime": "2018-07-09T09:04:42Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 1,
            "deactivationId": 1,
            "accountId": "B-M-1KQK3WU",
            "status": "IN_PROGRESS",
            "network": "STAGING",
            "createdBy": "jsmith",
            "createdTime": "2018-07-09T08:13:54Z",
            "lastModifiedTime": "2018-07-09T08:35:02Z"
        },
        {
            "edgeWorkerId": 42,
            "version": 2,
            "deactivationId": 2,
            "accountId": "B-M-1KQK3WU",
            "status": "COMPLETE",
            "network": "PRODUCTION",
            "createdBy": "asmith",
            "createdTime": "2018-07-10T14:23:42Z",
            "lastModifiedTime": "2018-07-10T14:53:25Z"
        }
    ]
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Run the List versions operation and select a version from the Version members response object.

  3. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/deactivations{?version}.

  4. View the response body for details on the Deactivation.

Deactivate an EdgeWorker version

Deactivate an existing EdgeWorker version on the Akamai network, either staging or production.

POST /edgeworkers/v1/ids/{edgeWorkerId}/deactivations

Sample: /edgeworkers/v1/ids/42/deactivations

Content-Type: application/json

Object type: Deactivation

Download schema: deactivations-post-request.json

Request body:

{
    "network": "PRODUCTION",
    "version": "2",
    "note": "EdgeWorker ID 42 is no longer used in production."
}
Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.

Status 201 application/json

Headers:

Location: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/edgeworkers/v1/edgeworkers/42/deactivations/3

Object type: Deactivation

Download schema: deactivation.json

Response body:

{
    "edgeWorkerId": 42,
    "version": 5,
    "deactivationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PRESUBMIT",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2019-04-05T18:17:46Z",
    "lastModifiedTime": "2019-04-05T18:17:46Z"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Build a JSON request object specifying the version you want to deactivate and the network on which to deactivate the EdgeWorker.

  3. POST the object to /edgeworkers/v1/ids/{edgeWorkerId}/deactivations.

  4. Optionally store the Location response header, which tells you where to GET the new deactivation from.

  5. View the response body for details on the Deactivation.

Get a deactivation

View details for a specific deactivation.

GET /edgeworkers/v1/ids/{edgeWorkerId}/deactivations/{deactivationId}

Sample: /edgeworkers/v1/ids/42/deactivations/3

Parameter Type Sample Description
URL path parameters
edgeWorkerId Integer 42 Unique identifier for an EdgeWorker.
deactivationId Integer 3 Unique identifier for an EdgeWorker deactivation.

Status 200 application/json

Object type: Deactivation

Download schema: deactivation.json

Response body:

{
    "edgeWorkerId": 42,
    "version": 9,
    "deactivationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PENDING",
    "network": "PRODUCTION",
    "note": "EdgeWorker ID 42 is no longer used in production.",
    "createdBy": "jsmith",
    "createdTime": "2018-08-04T11:42:56Z",
    "lastModifiedTime": "2018-08-04T12:00:03Z"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Run the List deactivations operation and select a deactivationId from the Deactivation members response object.

  3. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/deactivations/{deactivationId}.

List reports

View a list of available reports.

GET /edgeworkers/v1/reports

Status 200 application/json

Object type: Reports

Download schema: reports.json

Response body:

{
    "reports": [
        {
            "reportId": 1,
            "name": "Report summary",
            "description": "This report contains a summary of all reports.",
            "unavailable": false
        },
        {
            "reportId": 2,
            "name": "Initialization and execution times by EdgeWorker ID and event handler",
            "description": "This report lists execution and initialization times",
            "unavailable": false
        },
        {
            "reportId": 3,
            "name": "Execution statuses by EdgeWorker ID and event handler",
            "description": "This report lists executions success and error statuses, grouped by execution status."
        },
        {
            "reportId": 4,
            "name": "Memory usage by EdgeWorker ID and event handler",
            "description": "This report lists memory used by the execution of event handlers, grouped by event handler."
        }
    ]
}

Get an EdgeWorker report

View details for a specific EdgeWorker.

GET /edgeworkers/v1/reports/{reportId}{?start,edgeWorker,end,status,eventHandler}

Sample: /edgeworkers/v1/reports/2?start=2020-01-04T10%3A00%3A00Z&edgeWorker=42-1.0&end=2020-01-04T12%3A00%3A00Z&status=timeoutError&eventHandler=onClientRequest

Parameter Type Sample Description
URL path parameters
reportId Integer 2 Unique identifier of an EdgeWorker report.
Required query parameters
edgeWorker String 42-1.0 Filter by EdgeWorker ID such as 42 or more specific version such as 42-1.0
start String 2020-01-04T10:00:00Z ISO 8601 timestamp indicating the start time of the EdgeWorker report.
Optional query parameters
end String 2020-01-04T12:00:00Z ISO 8601 timestamp indicating the end time of the EdgeWorker report. If not specified, the end time defaults to the current time.
eventHandler Enumeration onClientRequest Filter EdgeWorkers by the event that triggers them, either onClientRequest, onOriginRequest, onOriginResponse, onClientResponse, or responseProvider.
status Enumeration timeoutError Filter by the EdgeWorker status, either success, genericError, unknownEdgeWorkerId, unimplementedEventHandler, runtimeError, executionError, timeoutError, resourceLimitHit, cpuTimeoutError, wallTimeoutError, initCpuTimeoutError, or initWallTimeoutError.

Status 200 application/json

Object type: Reports

Download schema: report.json

Response body:

{
    "reportId": 2,
    "name": "Initialization and execution times by EdgeWorker ID and event handler",
    "description": "This report lists execution and initialization times, grouped by EdgeWorker ID and event handler.",
    "start": "2020-08-17T00:00:00Z",
    "end": "2020-08-17T20:00:00Z",
    "data": [
        {
            "edgeWorkerId": 37017,
            "data": {
                "onClientRequest": [
                    {
                        "startDateTime": "2016-08-17T00:00:00Z",
                        "edgeWorkerVersion": "0.8",
                        "execDuration": {
                            "avg": 654,
                            "min": 554,
                            "max": 754
                        },
                        "invocations": 7
                    },
                    {
                        "startDateTime": "2016-08-17T00:05:00Z",
                        "edgeWorkerVersion": "0.9",
                        "execDuration": {
                            "avg": 453,
                            "min": 454,
                            "max": 459
                        },
                        "invocations": 5
                    }
                ],
                "onOriginRequest": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 234,
                            "min": 134,
                            "max": 334
                        },
                        "invocations": 6
                    }
                ],
                "onOriginResponse": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 324,
                            "min": 224,
                            "max": 424
                        },
                        "invocations": 2
                    }
                ],
                "onClientResponse": [
                    {
                        "startDateTime": "2016-08-17T04:00:10Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 275,
                            "min": 175,
                            "max": 375
                        },
                        "invocations": 6
                    }
                ],
                "responseProvider": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 324,
                            "min": 224,
                            "max": 424
                        },
                        "invocations": 2
                    }
                ],
                "init": [
                    {
                        "startDateTime": "2016-08-17T00:00:00Z",
                        "edgeWorkerVersion": "0.8",
                        "initDuration": {
                            "avg": 654,
                            "min": 554,
                            "max": 754
                        },
                        "invocations": 7
                    }
                ]
            }
        }
    ]
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from one of the EdgeWorker objects in the response.

  2. Run the List reports operation and select a reportId from the Report response objects.

  3. Specify the start time and optionally the end time of the report you want to view.

  4. Set the status parameter if you want to filter results by the status code that occurs when they execute.

  5. Set the eventHandler parameter if you want to filter results by the event that triggers them.

  6. Make a GET request to /edgeworkers/v1/reports/{reportId}{?start,edgeWorker,end,status,eventHandler}.

Get a secure token

A generated authentication token, for use with enhanced debug headers for EdgeWorkers. See Enhanced debug headers in the EdgeWorkers User Guide.

GET /edgeworkers/v1/secure-token/{propertyId}{?acl,url,expiry,network}

Sample: /edgeworkers/v1/secure-token/123456789?acl=/tmp&url=/test&expiry=30&network=STAGING

Parameter Type Sample Description
URL path parameters
propertyId Integer 123456789 Unique identifier for a property.
Optional query parameters
acl String /tmp Path prefix of the response pages to debug. This value can be a pattern that matches multiple pages, and is explicitly part of the final token. The default is /*. If you specify an acl, don’t specify a url.
expiry Integer 30 Number of minutes before the authentication token expires, from a minute to an hour. The default is 15.
network Enumeration STAGING The network on which to use this authentication token, either STAGING or PRODUCTION. If not specified, the token is created for the network where the last property version activation occurred.
url String /test Exact path of the response pages to debug. This value is not explicitly part of the final token, but is used as a salt in the HMAC computation. If you specify a url, don’t specify an acl.

Status 200 application/json

Object type: SecureToken

Download schema: secure-token.json

Response body:

{
    "akamaiEwTrace": "st=1606935722~exp=1606936622~acl=/*~hmac=fab65d016f7b72f57e3e7f6e0875517c35fd63efa510ff90b765af83daa34403"
}
  1. Run the List EdgeWorker IDs operation and select an edgeWorkerId from the EdgeWorker members response object.

  2. Make a GET request to /edgeworkers/v1/ids/{edgeWorkerId}/secure-token to get an authentication token, for use with enhanced debug headers for EdgeWorkers.

Data

This section details each type of data object that the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Permissions

This section describes EdgeWorker capabilities allowed within the Akamai group.

Download schema: group.json

Sample GET response:

{
    "groupId": 109795,
    "groupName": "ESSL Behavior Tests",
    "capabilities": [
        "VIEW",
        "VIEW_VERSION",
        "VIEW_ACTIVATION"
    ]
}

Permissions members

Member Type Description
Permissions: This section describes EdgeWorker capabilities allowed within the Akamai group.
capabilities Array List of EdgeWorker capabilities allowed within the group, including VIEW, EDIT, VIEW_VERSION, CREATE_VERSION, VIEW_ACTIVATION, and ACTIVATE.
groupId Integer Unique identifier of the Akamai group specified when the EdgeWorker was created.
groupName String Name of the Akamai group specified when the EdgeWorker was created.

Contract

This section provides a set of contract IDs that you use to list resource tiers.

Download schema: contract-ids.json

Sample GET response:

{
    "contractIds": [
        "1-599K",
        "B-M-28QYF3M"
    ]
}

Contract members

Member Type Description
Contract: This section provides a set of contract IDs that you use to list resource tiers.
contractIds String List of contract IDs.

ResourceTier

The resource tier defines the limits and billing rate applied to an EdgeWorker.

Download schema: resource-tier.json

Sample GET response:

{
    "resourceTiers": [
        {
            "resourceTierId": 100,
            "resourceTierName": "Basic Compute",
            "edgeWorkerLimits": [
                {
                    "limitName": "Maximum CPU time during initialization",
                    "limitValue": 30,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time during initialization",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel per EdgeWorker ID",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum memory usage per event handler",
                    "limitValue": 1310720,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time per event handler",
                    "limitValue": 10,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time per event handler",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed from a parent request",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel with the parent request",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time per HTTP sub-request",
                    "limitValue": 0,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size per HTTP sub-request",
                    "limitValue": 0,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum memory usage for responseProvider",
                    "limitValue": 2097152,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time for responseProvider",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time for responseProvider",
                    "limitValue": 4000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed for responseProvider",
                    "limitValue": 50,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel for responseProvider",
                    "limitValue": 5,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time for HTTP sub-requests during the execution of the responseProvider event handler",
                    "limitValue": 1000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size for HTTP sub-requests during the responseProvider event handler",
                    "limitValue": 1048576,
                    "limitUnit": "BYTE"
                }
            ]
        },
        {
            "resourceTierId": 200,
            "resourceTierName": "Dynamic Compute",
            "edgeWorkerLimits": [
                {
                    "limitName": "Maximum CPU time during initialization",
                    "limitValue": 30,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time during initialization",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel per EdgeWorker ID",
                    "limitValue": 0,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum memory usage per event handler",
                    "limitValue": 1310720,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time per event handler",
                    "limitValue": 50,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time per event handler",
                    "limitValue": 4000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed from a parent request",
                    "limitValue": 1,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel with the parent request",
                    "limitValue": 1,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time per HTTP sub-request",
                    "limitValue": 1000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size per HTTP sub-request",
                    "limitValue": 1048576,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum memory usage for responseProvider",
                    "limitValue": 2097152,
                    "limitUnit": "BYTE"
                },
                {
                    "limitName": "Maximum CPU time for responseProvider",
                    "limitValue": 100,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum wall time for responseProvider",
                    "limitValue": 4000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed for responseProvider",
                    "limitValue": 50,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum number of HTTP sub-requests allowed in parallel for responseProvider",
                    "limitValue": 5,
                    "limitUnit": "COUNT"
                },
                {
                    "limitName": "Maximum wall time for HTTP sub-requests during the execution of the responseProvider event handler",
                    "limitValue": 1000,
                    "limitUnit": "MILLISECOND"
                },
                {
                    "limitName": "Maximum response size for HTTP sub-requests during the execution of the responseProvider event handler",
                    "limitValue": 1048576,
                    "limitUnit": "BYTE"
                }
            ]
        }
    ]
}

ResourceTier members

Member Type Description
ResourceTier: The resource tier defines the limits and billing rate applied to an EdgeWorker.
edgeWorkerLimits ResourceTier.edgeWorkerLimits[] Provides details for an EdgeWorker limit.
resourceTierId Integer Unique identifier of the resource tier.
resourceTierName String Name of the resource tier.
ResourceTier.edgeWorkerLimits[]: Provides details for an EdgeWorker limit.
limitName String Name of the limit.
limitUnit Enumeration Unit of the limit, either BYTE, MILLISECOND, or COUNT.
limitValue Integer Value of the limit.

EdgeWorker

Attributes of an EdgeWorker.

Download schema: id-put-request.json, id.json

Sample POST request:

{
    "groupId": 72297,
    "name": "Ew_42",
    "resourceTierId": 100
}

Sample PUT request:

{
    "groupId": 123456,
    "name": "New EdgeWorker Name"
}

EdgeWorker members

Member Type POST PUT Description
EdgeWorker: Attributes of an EdgeWorker.
accountId String Read-only. Identifier for the account within which the EdgeWorker was created.
createdBy String Read-only. Username of the person who created the EdgeWorker.
createdTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker was created.
edgeWorkerId Integer Read-only. Unique identifier of the EdgeWorker.
groupId Integer Identifies a group to assign to the EdgeWorker.
lastModifiedBy String Read-only. Username of the person who most recently updated the EdgeWorker.
lastModifiedTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker was most recently modified.
name String A name you assign to the EdgeWorker.
resourceTierId Integer Unique identifier of a resource tier.

Validation

Provides details for an EdgeWorker code bundle validation.

Download schema: validation.json

Sample POST request:

{
    "errors": [
        {
            "type": "STATIC_VALIDATION_FAILED",
            "message": "static validation failed : main.js::9:16 SyntaxError: Unexpected identifier."
        },
        {
            "type": "INVALID_MANIFEST",
            "message": "manifest file is invalid"
        }
    ]
}

Validation members

Member Type Required Description
Validation: Provides details for an EdgeWorker code bundle validation.
errors Validation.errors[] Provides details for an EdgeWorker code bundle validation error.
Validation.errors[]: Provides details for an EdgeWorker code bundle validation error.
message String Read-only. Message containing more details about the validation error.
type Enumeration Read-only. The type of the validation error, either EMPTY_TARBALL, MAX_COMPRESSED_SIZE_EXCEEDED, INVALID_GZIP_FORMAT, MAX_UNCOMPRESSED_SIZE_EXCEEDED, INVALID_TAR_ARCHIVE, MISSING_MANDATORY_FILES, INVALID_MANIFEST, or STATIC_VALIDATION_FAILED. See Validation error types.

Version

Provides details for an EdgeWorker version.

Download schema: version.json

Sample POST request:

{
    "edgeWorkerId": 42,
    "version": 5,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-05T18:17:46Z"
}

Sample GET response:

{
    "edgeWorkerId": 42,
    "version": 3,
    "accountId": "B-M-1KQK3WU",
    "checksum": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
    "createdBy": "jsmith",
    "createdTime": "2018-07-09T21:51:07Z"
}

Version members

Member Type Required Description
Version: Provides details for an EdgeWorker version.
accountId String Read-only. Identifier for the account where the EdgeWorker was created.
checksum String Read-only. A SHA–256 hash digest of the tarball.
createdBy String Read-only. Username of the person who created the EdgeWorker version.
createdTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker version was created.
edgeWorkerId Integer Read-only. Unique identifier of the EdgeWorker.
sequenceNumber String Read-only. An incrementing number indicating the upload order of the EdgeWorker versions.
version String Read-only. Unique identifier of the EdgeWorker version.

Activation

Information required to create an EdgeWorker activation.

Download schema: activations-post-request.json, activation.json

Sample POST request:

{
    "network": "PRODUCTION",
    "version": "2"
}

Sample GET response:

{
    "edgeWorkerId": 42,
    "version": 9,
    "activationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PENDING",
    "network": "PRODUCTION",
    "createdBy": "jsmith",
    "createdTime": "2018-08-04T11:42:56Z",
    "lastModifiedTime": "2018-08-04T12:00:03Z"
}

Activation members

Member Type Required Description
Activation: Information required to create an EdgeWorker activation.
accountId String Read-only. Identifier for the account within which the EdgeWorker was created.
activationId Integer Read-only. Unique identifier of the activation.
createdBy String Read-only. Username of the person who created the EdgeWorker.
createdTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker was created.
edgeWorkerId Integer Read-only. Unique identifier of the EdgeWorker.
lastModifiedTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker was most recently modified.
network Enumeration The network on which the version is activated, either PRODUCTION or STAGING.
status Enumeration Read-only. The activation status of the EdgeWorker version, either PRESUBMIT, PENDING, IN_PROGRESS, COMPLETE, ABORTED, ERROR, DELETED_BY_AKAMAI, or EXPIRED.
version String Unique identifier of the version that will be activated.

Deactivation

Information required to create an EdgeWorker deactivation.

Download schema: deactivations-post-request.json, deactivation.json

Sample POST request:

{
    "network": "PRODUCTION",
    "version": "2",
    "note": "EdgeWorker ID 42 is no longer used in production."
}

Sample GET response:

{
    "edgeWorkerId": 42,
    "version": 9,
    "deactivationId": 3,
    "accountId": "B-M-1KQK3WU",
    "status": "PENDING",
    "network": "PRODUCTION",
    "note": "EdgeWorker ID 42 is no longer used in production.",
    "createdBy": "jsmith",
    "createdTime": "2018-08-04T11:42:56Z",
    "lastModifiedTime": "2018-08-04T12:00:03Z"
}

Deactivation members

Member Type Required Description
Deactivation: Information required to create an EdgeWorker deactivation.
accountId String Read-only. Identifier for the account within which the EdgeWorker was created.
createdBy String Read-only. Username of the person who created the EdgeWorker.
createdTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker was created.
deactivationId Integer Read-only. Unique identifier of the deactivation.
edgeWorkerId Integer Read-only. Unique identifier of the EdgeWorker.
lastModifiedTime String Read-only. ISO 8601 timestamp indicating when the EdgeWorker was most recently modified.
network Enumeration The network on which the version is deactivated, either PRODUCTION or STAGING.
note String Note to specify why the version is being deactivated.
status Enumeration Read-only. The deactivation status of the EdgeWorker version, either PRESUBMIT, PENDING, IN_PROGRESS, COMPLETE, ABORTED, ERROR, DELETED_BY_AKAMAI, or EXPIRED.
version String Unique identifier of the version that will be deactivated.

Reports

This section describes attributes of an EdgeWorker report.

Download schema: report.json

Sample GET response:

{
    "reports": [
        {
            "reportId": 1,
            "name": "Report summary",
            "description": "This report contains a summary of all reports.",
            "unavailable": false
        },
        {
            "reportId": 2,
            "name": "Initialization and execution times by EdgeWorker ID and event handler",
            "description": "This report lists execution and initialization times",
            "unavailable": false
        },
        {
            "reportId": 3,
            "name": "Execution statuses by EdgeWorker ID and event handler",
            "description": "This report lists executions success and error statuses, grouped by execution status."
        },
        {
            "reportId": 4,
            "name": "Memory usage by EdgeWorker ID and event handler",
            "description": "This report lists memory used by the execution of event handlers, grouped by event handler."
        }
    ]
}

Reports members

Member Type Description
Reports: This section describes attributes of an EdgeWorker report.
data OverviewReport object,
ExecutionTimeReport array, or
ExecutionStatusReport array
Object containing data points of the EdgeWorker report.
description String Description of the EdgeWorker report.
end String ISO 8601 timestamp indicating the end time of the EdgeWorker report.
name String Name of the EdgeWorker report.
reportId Integer Unique identifier of the EdgeWorker report.
start String ISO 8601 timestamp indicating the start time of the EdgeWorker report.
unavailable Boolean Boolean stating if the report is available or not.

OverviewReport

Specifies summary data for each EdgeWorker’s usage.

Download schema: report-1.json

Sample report:

{
    "reportId": 1,
    "name": "Report Overview",
    "description": "This report contains a summary of all reports.",
    "start": "2020-08-17T00:00:00Z",
    "end": "2020-08-17T20:00:00Z",
    "data": {
        "invocations": {
            "total": 158
        },
        "successes": {
            "total": 121
        },
        "errors": {
            "total": 37
        },
        "execDuration": {
            "avg": 95.432,
            "min": 42,
            "max": 156
        },
        "initDuration": {
            "avg": 24.237,
            "min": 14,
            "max": 31
        },
        "memory": {
            "avg": 53701.9876,
            "min": 22567,
            "max": 132432
        }
    }
}

OverviewReport members

Member Type Description
OverviewReport: Specifies summary data for each EdgeWorker’s usage.
errors OverviewReport.errors Failed event handler executions.
execDuration OverviewReport.execDuration Execution duration.
initDuration OverviewReport.initDuration Initialization duration.
invocations OverviewReport.invocations Number of executions.
memory OverviewReport.memory Memory usage.
successes OverviewReport.successes Successful event handler executions.
OverviewReport.errors: Failed event handler executions.
total Integer Total number of failed executions.
OverviewReport.execDuration: Execution duration.
avg Integer Average clock time used by the execution of event handlers.
max Integer Maximum clock time used by the execution of event handlers.
min Integer Minimum clock time used by the execution of event handlers.
OverviewReport.initDuration: Initialization duration.
avg Integer Average clock time used to initialize the event handlers. The average is the sum of the initialization times divided by the number of executions.
max Integer Maximum clock time used to initialize the event handlers.
min Integer Minimum clock time used to initialize the event handlers.
OverviewReport.invocations: Number of executions.
total Integer Total number of executions.
OverviewReport.memory: Memory usage.
avg Integer Average memory used by the execution of event handlers.
max Integer Maximum memory used by the execution of event handlers.
min Integer Minimum memory used by the execution of event handlers.
OverviewReport.successes: Successful event handler executions.
total Integer Total number of successful executions.

ExecutionTimeReport

Specifies time series data for each EdgeWorker’s usage.

Download schema: report-2.json

Sample report:

{
    "reportId": 2,
    "name": "Initialization and execution times by EdgeWorker ID and event handler",
    "description": "This report lists execution and initialization times, grouped by EdgeWorker ID and event handler.",
    "start": "2020-08-17T00:00:00Z",
    "end": "2020-08-17T20:00:00Z",
    "data": [
        {
            "edgeWorkerId": 37017,
            "data": {
                "onClientRequest": [
                    {
                        "startDateTime": "2016-08-17T00:00:00Z",
                        "edgeWorkerVersion": "0.8",
                        "execDuration": {
                            "avg": 654,
                            "min": 554,
                            "max": 754
                        },
                        "invocations": 7
                    },
                    {
                        "startDateTime": "2016-08-17T00:05:00Z",
                        "edgeWorkerVersion": "0.9",
                        "execDuration": {
                            "avg": 453,
                            "min": 454,
                            "max": 459
                        },
                        "invocations": 5
                    }
                ],
                "onOriginRequest": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 234,
                            "min": 134,
                            "max": 334
                        },
                        "invocations": 6
                    }
                ],
                "onOriginResponse": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 324,
                            "min": 224,
                            "max": 424
                        },
                        "invocations": 2
                    }
                ],
                "onClientResponse": [
                    {
                        "startDateTime": "2016-08-17T04:00:10Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 275,
                            "min": 175,
                            "max": 375
                        },
                        "invocations": 6
                    }
                ],
                "responseProvider": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "execDuration": {
                            "avg": 324,
                            "min": 224,
                            "max": 424
                        },
                        "invocations": 2
                    }
                ],
                "init": [
                    {
                        "startDateTime": "2016-08-17T00:00:00Z",
                        "edgeWorkerVersion": "0.8",
                        "initDuration": {
                            "avg": 654,
                            "min": 554,
                            "max": 754
                        },
                        "invocations": 7
                    }
                ]
            }
        }
    ]
}

ExecutionTimeReport members

Member Type Description
ExecutionTimeReport: Specifies time series data for each EdgeWorker’s usage.
data ExecutionTimeReport.data Data points grouped by event handler and initialization.
edgeWorkerId Integer Unique identifier for an EdgeWorker.
ExecutionTimeReport.data: Data points grouped by event handler and initialization.
{eventType} ExecutionTimeReport.data.{eventType}[] Aggregated execution or initialization durations.
ExecutionTimeReport.data.{eventType}[]: Aggregated execution or initialization durations.
edgeWorkerVersion String The EdgeWorker version that was active during the execution of event handlers.
execDuration ExecutionTimeReport.data.{eventType}[].execDuration Execution duration.
initDuration ExecutionTimeReport.data.{eventType}[].initDuration Initialization duration.
invocations Integer Number of aggregated executions or initializations.
startDateTime String Start date of the time period (ISO 8601).
ExecutionTimeReport.data.{eventType}[].execDuration: Execution duration.
avg Integer Average clock time used by the execution of event handlers.
max Integer Maximum clock time used by the execution of event handlers.
min Integer Minimum clock time used by the execution of event handlers.
ExecutionTimeReport.data.{eventType}[].initDuration: Initialization duration.
avg Integer Average clock time used to initialize the event handlers. The average is the sum of the initialization times divided by the number of executions.
max Integer Maximum clock time used to initialize the event handlers.
min Integer Minimum clock time used to initialize the event handlers.

ExecutionStatusReport

Specifies execution status data for each EdgeWorker.

Download schema: report-3.json

Sample report:

{
    "reportId": 3,
    "name": "Execution statuses by EdgeWorker ID and event handler",
    "description": "This report lists executions success and error statuses, grouped by event handler.",
    "start": "2020-08-17T00:00:00Z",
    "end": "2020-08-17T20:00:00Z",
    "data": [
        {
            "edgeWorkerId": 37017,
            "data": {
                "onClientRequest": [
                    {
                        "startDateTime": "2016-08-17T00:00:00Z",
                        "edgeWorkerVersion": "0.8",
                        "status": "success",
                        "invocations": 7
                    },
                    {
                        "startDateTime": "2016-08-17T00:05:00Z",
                        "edgeWorkerVersion": "0.9",
                        "status": "executionError",
                        "invocations": 5
                    }
                ],
                "onOriginRequest": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "status": "success",
                        "invocations": 6
                    }
                ],
                "onOriginResponse": [
                    {
                        "startDateTime": "2016-08-17T04:00:00Z",
                        "edgeWorkerVersion": "1.0",
                        "status": "success",
                        "invocations": 2
                    }
                ],
                "onClientResponse": [
                    {
                        "startDateTime": "2016-08-17T04:00:10Z",
                        "edgeWorkerVersion": "1.0",
                        "status": "success",
                        "invocations": 6
                    }
                ],
                "responseProvider": [
                    {
                        "startDateTime": "2016-08-17T04:00:10Z",
                        "edgeWorkerVersion": "1.0",
                        "status": "success",
                        "invocations": 1
                    }
                ]
            }
        }
    ]
}

ExecutionStatusReport members

Member Type Description
ExecutionStatusReport: Specifies execution status data for each EdgeWorker.
data ExecutionStatusReport.data Data points grouped by event handler.
edgeWorkerId Integer Unique identifier for an EdgeWorker.
ExecutionStatusReport.data: Data points grouped by event handler.
{eventType} ExecutionStatusReport.data.{eventType}[] Aggregated execution status.
ExecutionStatusReport.data.{eventType}[]: Aggregated execution status.
edgeWorkerVersion String The EdgeWorker version that was active during the execution of event handlers.
invocations Integer Number of aggregated executions.
startDateTime String Start date of the time period (ISO 8601).
status String Execution status.

SecureToken

A generated authentication token, for use with enhanced debug headers for EdgeWorkers. See Enhanced debug headers in the EdgeWorkers User Guide.

Download schema: secure-token.json

Sample GET response:

{
    "akamaiEwTrace": "st=1606935722~exp=1606936622~acl=/*~hmac=fab65d016f7b72f57e3e7f6e0875517c35fd63efa510ff90b765af83daa34403"
}

SecureToken members

Member Type Description
SecureToken: A generated authentication token, for use with enhanced debug headers for EdgeWorkers. See Enhanced debug headers in the EdgeWorkers User Guide.
akamaiEwTrace String Authentication token

Errors

This section details the API’s common responses to error cases. You’ll find the API’s range of response status codes for both error and success cases.

Error responses

This API adheres to the Problem Details for HTTP APIs standard, and returns detailed error responses, such as:

{
    "type": "/edgeworkers/error-types/edgeworkers-invalid-argument",
    "title": "Invalid Argument.",
    "detail": "Invalid tarball provided",
    "instance": "/devpops-api/error-instances/1fb2b105-e976-4e28-ba26-fa649a0d86ff",
    "status": 400
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 The resource was created successfully.
400 Invalid or missing required parameters.
401 Invalid authorization credentials.
403 The client is not authorized to invoke the service. See Get started for information on API authorization.
404 Couldn’t find the requested resource.
422 System limit reached. See Resource limiting.
500 Can’t return requested resource. May be corrupted.
502 Gateway unavailable to process request.
503 Service is temporarily unavailable.