API
TrainingSupportCommunity

purge-usage-by-clientname

🚧

The purge-usage-by-clientname report is being discontinued

This report is deprecated and will be deactivated on July 1, 2025. As an alternative, use the new delivery/purge/usage report, based on the Reporting API v2.

The following shows how to generate the purge-usage-by-clientname report using either the Reporting API's Generate a report POST operation or the Get a cacheable report GET operation. Details about each report's supported products, metrics, filters, and available data intervals are also available dynamically by running the API's Get a report type operation, also shown below. See also other available reports.

Report definition

Details of purge requests and objects by client name.

Business object: account_id

Data available for: 45 days

Required products: EDGECONTROL

Available metrics

MetricDescription
Data metrics
objectCountObject count.
objectPercentObject percent.
requestCountTotal traffic by segments.
requestPercentRequest percent.

Available filters

FilterTypeDescription
Required filters
contract_typeStringA contract type ID a given user has access to.
Optional filters
client_idStringClient Id.
client_nameStringClient name.
client_ownerStringClient owner.
environmentEnumerationEnvironment.
STAGING: Staging.
PRODUCTION: Production.
request_actionEnumerationRequest action.
invalidate: Invalidate.
delete: Delete.
request_sourceEnumerationRequest source.
EDGEGRID: Edgegrid.
PORTAL: Portal.
request_typeEnumerationRequest type.
CPCODE: CP code
VCD: VCD
ARL: ARL
TAG: TAG
URL: URL
response_classEnumerationA class of HTTP response status codes, from 0xx through 6xx.
0xx: An aborted action on the client side.
1xx: An informational response, like Continue.
2xx: A successful response.
3xx: Success, but a redirect where the thing you want is somewhere else.
4xx: Error, where there’s some problem with the client request.
5xx: Error, where there’s some problem with how the API server responded to the client request.
6xx: Invalid headers (defined by Akamai).
response_codeStringAn HTTP response status code, for example, 201.
response_statusEnumerationAn indicator of whether the HTTP response resulted in success or an error.
success: Successful HTTP response status.
error: Error HTTP response status.

POST request

POST /reporting-api/v1/reports/purge-usage-by-clientname/versions/2/report-data{?start,end}

Sample: /reporting-api/v1/reports/purge-usage-by-clientname/versions/2/report-data?start=2023-05-01T00%3A00%3A00Z&end=2023-06-01T00%3A00%3A00Z

Query parameters

ParameterTypeSampleDescription
Required
startString2023-05-01T00:00:00ZSpecifies the start of the reported period as an ISO-8601 timestamp with optional time zone. The report includes data that matches the start value’s timestamp.
endString2023-06-01T00:00:00ZSpecifies the end of the reported period as an ISO-8601 timestamp with optional time zone. The report excludes any data that matches the end value’s timestamp.

JSON request members

MemberTypeDescription
objectIdsArraySpecifies the account_id value you want to report on.
metricsArrayThe set of desired metrics. If omitted, the report includes all available metrics.
filtersMap of ArraysSpecifies a set of custom filters, with each filter's name keying an array with each filter's set of values.

Request body:

{
    "objectIds": [
        "1-123A"
    ],
    "metrics": [
        "objectCount",
        "objectPercent",
        "requestCount",
        "requestPercent"
    ],
    "filters": {
        "client_id": [
            "client2",
            "client4"
        ],
        "client_name": [
            "name1",
            "name2"
        ],
        "client_owner": [
            "owner1",
            "owner2"
        ],
        "contract_type": [
            "1-3CV382"
        ],
        "environment": [
            "STAGING",
            "PRODUCTION"
        ],
        "request_action": [
            "invalidate",
            "delete"
        ],
        "request_source": [
            "EDGEGRID",
            "PORTAL"
        ],
        "request_type": [
            "ARL",
            "VCD"
        ],
        "response_class": [
            "1xx",
            "3xx"
        ],
        "response_code": [
            "404",
            "200"
        ],
        "response_status": [
            "success",
            "error"
        ]
    }
}

GET request

GET /reporting-api/v1/reports/purge-usage-by-clientname/versions/2/report-data{?start,end,objectIds,metrics,filters}

Sample: /reporting-api/v1/reports/purge-usage-by-clientname/versions/2/report-data?start=2023-05-01T00%3A00%3A00Z&end=2023-06-01T00%3A00%3A00Z&objectIds=1-123A&metrics=objectCount%2CobjectPercent&filters=client_id%3Dclient2%2Cclient_id%3Dclient5%2Cclient_name%3Dname3%2Cclient_name%3Dname4

Query parameters

ParameterTypeSampleDescription
Required
startString2023-05-01T00:00:00ZSpecifies the start of the reported period as an ISO-8601 timestamp with optional time zone. The report includes data that matches the start value’s timestamp.
endString2023-06-01T00:00:00ZSpecifies the end of the reported period as an ISO-8601 timestamp with optional time zone. The report excludes any data that matches the end value’s timestamp.
objectIdsString1-123ASpecifies the account_id value you want to report on.
Optional
metricsStringobjectCount,object​PercentSpecifies a comma-separated list of metrics to include in the report, otherwise all metrics if omitted. The set of available metrics depends on the type of report. URL-encode the entire value in the GET request.
filtersStringclient_id=client2,​client_​id=​client5,​client_​name=​name3,​client_​name=​name4Specifies criteria to filter the report’s data. The set of available filters depends on the type of report. Separate each filter name and value with an equals (=) character, and separate various name/value pairs with commas (,). To specify more than one filter value, repeat the filter name. See the accompanying example for guidance. URL-encode the entire value in the GET request.

JSON response

Status 200 application/json

Response body:

{
    "metadata": {
        "name": "purge-usage-by-clientname",
        "version": "2",
        "outputType": "FLAT",
        "groupBy": [
            "client_name",
            "client_owner"
        ],
        "start": "2023-05-01T00:00:00Z",
        "end": "2023-06-01T00:00:00Z",
        "availableDataEnds": null,
        "suggestedRetryTime": null,
        "rowCount": 4,
        "filters": [
            {
                "name": "client_id",
                "values": [
                    "client3",
                    "client1"
                ]
            },
            {
                "name": "client_name",
                "values": [
                    "name1",
                    "name4"
                ]
            },
            {
                "name": "client_owner",
                "values": [
                    "owner5",
                    "owner3"
                ]
            },
            {
                "name": "contract_type",
                "values": [
                    "1-3CV382"
                ]
            },
            {
                "name": "environment",
                "values": [
                    "STAGING",
                    "PRODUCTION"
                ]
            },
            {
                "name": "request_action",
                "values": [
                    "invalidate",
                    "delete"
                ]
            },
            {
                "name": "request_source",
                "values": [
                    "PORTAL",
                    "EDGEGRID"
                ]
            },
            {
                "name": "request_type",
                "values": [
                    "VCD",
                    "URL"
                ]
            },
            {
                "name": "response_class",
                "values": [
                    "4xx",
                    "0xx"
                ]
            },
            {
                "name": "response_code",
                "values": [
                    "100",
                    "500"
                ]
            },
            {
                "name": "response_status",
                "values": [
                    "success",
                    "error"
                ]
            }
        ],
        "columns": [
            {
                "name": "groupBy",
                "label": "client_name"
            },
            {
                "name": "groupBy",
                "label": "client_owner"
            },
            {
                "name": "objectCount",
                "label": "Objects"
            },
            {
                "name": "objectPercent",
                "label": "Objects %"
            },
            {
                "name": "requestCount",
                "label": "Requests"
            },
            {
                "name": "requestPercent",
                "label": "Requests %"
            }
        ],
        "objectType": "account_id",
        "objectIds": [
            "1-123A"
        ]
    },
    "data": [
        {
            "client_name": "name2",
            "client_owner": "owner5",
            "objectCount": "1238",
            "objectPercent": "27",
            "requestCount": "4065",
            "requestPercent": "32"
        },
        {
            "client_name": "name5",
            "client_owner": "owner1",
            "objectCount": "3964",
            "objectPercent": "94",
            "requestCount": "737",
            "requestPercent": "28"
        },
        {
            "client_name": "name4",
            "client_owner": "owner4",
            "objectCount": "2245",
            "objectPercent": "61",
            "requestCount": "2368",
            "requestPercent": "28"
        },
        {
            "client_name": "name3",
            "client_owner": "owner3",
            "objectCount": "879",
            "objectPercent": "89",
            "requestCount": "4322",
            "requestPercent": "53"
        }
    ],
    "summaryStatistics": {}
}

CSV response

Status 200 text/csv

Response Body:

#METADATA_START
name,purge-usage-by-clientname
version,2
source,purge-usage-by-clientname/versions/2
groupBy,client_name,client_owner
start,2023-05-01T00:00:00Z
end,2023-06-01T00:00:00Z
availableDataEnds,
suggestedRetryTime,
rowCount,4
objectType,account_id
objectIds,1-123A
client_id,client3,client1
client_name,name1,name4
client_owner,owner5,owner3
contract_type,1-3CV382
environment,STAGING,PRODUCTION
request_action,invalidate,delete
request_source,PORTAL,EDGEGRID
request_type,VCD,URL
response_class,4xx,0xx
response_code,100,500
response_status,success,error
#METADATA_END

#SUMMARYSTATISTICS_START

#SUMMARYSTATISTICS_END

#COLUMNS_START
client_name,client_owner,objectCount,objectPercent,requestCount,requestPercent
#COLUMNS_END

#DATA_START
name2,owner5,1238,27,4065,32
name5,owner1,3964,94,737,28
name4,owner4,2245,61,2368,28
name3,owner3,879,89,4322,53
#DATA_END

Get report details

This sample Get a report type operation gets the same information you need to run the purge-usage-by-clientname report as provided in this reference documentation, but available dynamically to your API client application.

GET /reporting-api/v1/reports/purge-usage-by-clientname/versions/2

Status 200 application/json

Response body:

{
    "name": "purge-usage-by-clientname",
    "description": "Details of purge requests and objects by client name.",
    "businessObjectName": "account_id",
    "version": 2,
    "status": "DEPRECATED",
    "deprecated": true,
    "timeBased": false,
    "supportsPagination": false,
    "outputType": "FLAT",
    "requiredProducts": [
        "EDGECONTROL"
    ],
    "requiredRoles": [
        "IDM: API Clients - Admin Access"
    ],
    "available": true,
    "metrics": [
        {
            "name": "requestCount",
            "description": "Total traffic by segments.",
            "label": "Requests",
            "unit": "COUNT",
            "summaryStatistic": false
        },
        {
            "name": "requestPercent",
            "description": "Request percent.",
            "label": "Requests %",
            "unit": "RATIO",
            "summaryStatistic": false
        },
        {
            "name": "objectCount",
            "description": "Object count.",
            "label": "Objects",
            "unit": "COUNT",
            "summaryStatistic": false
        },
        {
            "name": "objectPercent",
            "description": "Object percent.",
            "label": "Objects %",
            "unit": "RATIO",
            "summaryStatistic": false
        }
    ],
    "groupOutlyingValues": {
        "enabled": false
    },
    "groupBy": [
        "client_name",
        "client_owner"
    ],
    "filters": [
        {
            "name": "client_owner",
            "type": "string",
            "description": "Client owner.",
            "required": false
        },
        {
            "name": "response_code",
            "type": "string",
            "description": "An HTTP response status code, for example, 201.",
            "required": false
        },
        {
            "name": "environment",
            "type": "enum",
            "description": "Environment.",
            "values": [
                {
                    "value": "STAGING",
                    "description": "Staging."
                },
                {
                    "value": "PRODUCTION",
                    "description": "Production."
                }
            ],
            "required": false
        },
        {
            "name": "response_status",
            "type": "enum",
            "description": "An indicator of whether the HTTP response resulted in success or an error.",
            "values": [
                {
                    "value": "success",
                    "description": "Successful HTTP response status."
                },
                {
                    "value": "error",
                    "description": "Error HTTP response status."
                }
            ],
            "required": false
        },
        {
            "name": "contract_type",
            "type": "string",
            "description": "A contract type ID a given user has access to.",
            "required": true
        },
        {
            "name": "client_id",
            "type": "string",
            "description": "Client Id.",
            "required": false
        },
        {
            "name": "request_action",
            "type": "enum",
            "description": "Request action.",
            "values": [
                {
                    "value": "invalidate",
                    "description": "Invalidate."
                },
                {
                    "value": "delete",
                    "description": "Delete."
                }
            ],
            "required": false
        },
        {
            "name": "request_source",
            "type": "enum",
            "description": "Request source.",
            "values": [
                {
                    "value": "EDGEGRID",
                    "description": "Edgegrid."
                },
                {
                    "value": "PORTAL",
                    "description": "Portal."
                }
            ],
            "required": false
        },
        {
            "name": "client_name",
            "type": "string",
            "description": "Client name.",
            "required": false
        },
        {
            "name": "request_type",
            "type": "enum",
            "description": "Request type.",
            "values": [
                {
                    "value": "CPCODE",
                    "description": "CP code"
                },
                {
                    "value": "VCD",
                    "description": "VCD"
                },
                {
                    "value": "ARL",
                    "description": "ARL"
                },
                {
                    "value": "TAG",
                    "description": "TAG"
                },
                {
                    "value": "URL",
                    "description": "URL"
                }
            ],
            "required": false
        },
        {
            "name": "response_class",
            "type": "enum",
            "description": "A class of HTTP response status codes, from 0xx through 6xx.",
            "values": [
                {
                    "value": "0xx",
                    "description": "An aborted action on the client side."
                },
                {
                    "value": "1xx",
                    "description": "An informational response, like Continue."
                },
                {
                    "value": "2xx",
                    "description": "A successful response."
                },
                {
                    "value": "3xx",
                    "description": "Success, but a redirect where the thing you want is somewhere else."
                },
                {
                    "value": "4xx",
                    "description": "Error, where there’s some problem with the client request."
                },
                {
                    "value": "5xx",
                    "description": "Error, where there’s some problem with how the API server responded to the client request."
                },
                {
                    "value": "6xx",
                    "description": "Invalid headers (defined by Akamai)."
                }
            ],
            "required": false
        }
    ],
    "intervals": [
        "MONTH",
        "WEEK",
        "DAY",
        "HOUR",
        "FIVE_MINUTES"
    ],
    "dataRetentionDays": 45,
    "links": [
        {
            "rel": "self",
            "href": "/reporting-api/v1/reports/purge-usage-by-clientname/versions/2"
        },
        {
            "rel": "versions",
            "href": "/reporting-api/v1/reports/purge-usage-by-clientname/versions"
        },
        {
            "rel": "all-reports",
            "href": "/reporting-api/v1/reports"
        },
        {
            "rel": "execute-report",
            "href": "/reporting-api/v1/reports/purge-usage-by-clientname/versions/2/report-data"
        }
    ]
}