improved

WAS: Pagination Update

The Tenable.io Web Application Scanning v2 API page request and response format has been updated to match the Tenable.io Vulnerability Management format. This change brings consistent pagination across the various Tenable.io APIs. The old page request and response format has been deprecated in favor of the new page request and response format.

Warning

The old page request and response format has been deprecated. Backwards compatibility and support for both formats will remain until June 11, 2021. Please update any existing integrations that your organization has before this date.

This update affects the following endpoints:

API EndpointName
GET /was/v2/configsList configurations
GET /was/v2/scansList scans
GET /was/v2/scans/{scan_id}/notesGet scan notes
GET /was/v2/scans/{scan_id}/vulnerabilitiesList vulnerabilities for scan
GET /was/v2/vulnerabilitiesList vulnerabilities
GET /was/v2/templatesList Tenable-provided templates
GET /was/v2/user-templatesList user-defined templates
GET /was/v2/pluginsList plugins

New page request and response format

Request

You can specify pagination preferences for responses using the following query parameters:

ParameterTypeDescription
limitint32The number of records to retrieve. If this parameter is omitted, Tenable.io uses the default value of 10. The minimum value is 0 and the maximum value is 200. If you need to retrieve more than 200 records, use the offset value to iterate through page responses.
offsetint32The starting record to retrieve. If this parameter is omitted, Tenable.io uses the default value of 0.
sortstringThe field you want to use to sort the results by along with the sort order. The field is specified first, followed by a colon, and the order is specified second (asc or desc). For example, name:desc would sort results by the name field in descending order.

If you specify multiple fields, the fields must be separated by commas. For example, name:desc,created_at:asc would first sort results by the name field in descending order and then by the created_at field in ascending order.

Response

The new response format returns the result set within an items object and the pagination information within a pagination object.

{
  "pagination": { },
  "items": [...]
}

Example

For example, to request a list of scan configurations from the GET /was/v2/configs endpoint (using the new request format), limit the result set to two records, and sort the result set by the creation date (ascending) and name (descending), you would use the following request format:

https://cloud.tenable.com/was/v2/configs?limit=2&sort=created_at:asc,name:desc

The response format from this request would be:

{
  "pagination": {
    "total": 1690,
    "offset": 0,
    "limit": 2,
    "sort": [
      {
        "name": "created_at",
        "order": "asc"
      },
      {
        "name": "name",
        "order": "desc"
      }
    ]
  },
  "items": [
    {
      "config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
      "owner_id": "4dc95b60-8821-4280-be08-265ae01882a7",
      "is_shared": false,
      "user_permissions": "configure",
      "name": "Example 1",
      "target": "http://example.com/",
      "description": "Example 1",
      "created_at": "1970-01-19T10:02:34.808Z",
      "updated_at": "2020-06-05T11:00:08Z",
      "schedule": null,
      "template_id": "b223f18e-5a94-4e02-b560-77a4a8246cd3",
      "last_scan": {
        "scan_id": "4f9e9182-b1f3-4b7c-a931-c3e502f5c155",
        "user_id": "5ff4ad03-f168-4632-90fb-babf376579e9",
        "config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
        "asset_id": "6febe7b0-5dc0-43ec-afc1-aa8a7a6a7ae5",
        "target": "http://example.com/",
        "application_uri": "http://example.com/",
        "created_at": "2020-10-07T22:35:20.533Z",
        "updated_at": "2020-10-07T22:37:57.449Z",
        "started_at": "2020-10-07T22:35:34.353Z",
        "finalized_at": "2020-10-07T22:37:57.436Z",
        "requested_action": "start",
        "status": "completed",
        "metadata": {
          "found_urls": 11,
          "queued_urls": 0,
          "scan_status": "running",
          "audited_urls": 1,
          "queued_pages": 0,
          "audited_pages": 1,
          "request_count": 2634,
          "response_time": 0
        },
        "scanner": {
          "group_name": "US Cloud Scanner"
        },
        "template_name": "scan"
      },
      "user_template": null
    },
    {
      "config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
      "owner_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
      "is_shared": false,
      "user_permissions": "configure",
      "name": "Example 2",
      "target": "http://192.0.2.119",
      "description": null,
      "created_at": "2020-02-05T23:16:11.883Z",
      "updated_at": "2020-02-05T23:16:11.883Z",
      "schedule": null,
      "template_id": "112f3e7f-d83a-4bba-b2c8-df2d22e2fa4c",
      "last_scan": {
        "scan_id": "934848fa-2e28-4f1e-a438-dcbeef89b5b5",
        "user_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
        "config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
        "asset_id": "22807f4e-d678-4c60-bcb9-6af2a0623f9b",
        "target": "http://192.0.2.119",
        "application_uri": "http://192.0.2.119",
        "created_at": "2020-02-19T16:52:17.264Z",
        "updated_at": "2020-02-19T16:55:59.154Z",
        "started_at": null,
        "finalized_at": null,
        "requested_action": "start",
        "status": "aborted",
        "metadata": {
          "estimate_crawl_percent_complete": 100,
          "queued_urls": 0,
          "scan_status": "running",
          "crawled_urls": 11,
          "queued_pages": 0,
          "audited_pages": 18,
          "request_count": 678,
          "response_time": 0
        },
        "scanner": null,
        "template_name": "overview"
      },
      "user_template": null
    }
  ]
}

Old page request and response format (deprecated)

For reference, information about the deprecated page request and response format is included below.

Request

Pagination preferences for responses using the old format (deprecated) were specified using the following query parameters:

ParameterTypeDescription
order_bystringThe field used to order the query results.
orderingstringThe sort order applied when sorting by the order_by parameter. Values include asc and desc. If your request omits the ordering query parameter, this value defaults to asc.
pageint32The starting record to retrieve. Use in combination with the size parameter to paginate results. The default value is 0.
sizeint32The page size of the query results. Use in combination with the page parameter to paginate results. The default value is 10.

Response

The old response format returned the result set within the data object. The pagination preferences were also returned.

{
  "page_number": 0,
  "page_size": 2,
  "order_by": "created_at",
  "ordering": "asc",
  "total_size": 1690,
  "data": [...]
}

Example

For example, to request a list of scan configurations from the GET /was/v2/configs endpoint (using the deprecated request format), limit the result set to two records, and sort the result set by the creation date in ascending order you would use the following request:

https://cloud.tenable.com/was/v2/configs?size=2&order_by=created_at&ordering=asc

The response format from this request would be:

{
  "page_number": 0,
  "page_size": 2,
  "order_by": "created_at",
  "ordering": "asc",
  "total_size": 1690,
  "data": [
    {
      "config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
      "owner_id": "4dc95b60-8821-4280-be08-265ae01882a7",
      "is_shared": false,
      "user_permissions": "configure",
      "name": "Example 1",
      "target": "http://example.com/",
      "description": "Example 1",
      "created_at": "1970-01-19T10:02:34.808Z",
      "updated_at": "2020-06-05T11:00:08Z",
      "schedule": null,
      "template_id": "b223f18e-5a94-4e02-b560-77a4a8246cd3",
      "last_scan": {
        "scan_id": "4f9e9182-b1f3-4b7c-a931-c3e502f5c155",
        "user_id": "5ff4ad03-f168-4632-90fb-babf376579e9",
        "config_id": "24da4d67-bc7b-369d-bc73-826671a575cc",
        "asset_id": "6febe7b0-5dc0-43ec-afc1-aa8a7a6a7ae5",
        "target": "http://example.com/",
        "application_uri": "http://example.com/",
        "created_at": "2020-10-07T22:35:20.533Z",
        "updated_at": "2020-10-07T22:37:57.449Z",
        "started_at": "2020-10-07T22:35:34.353Z",
        "finalized_at": "2020-10-07T22:37:57.436Z",
        "requested_action": "start",
        "status": "completed",
        "metadata": {
          "found_urls": 11,
          "queued_urls": 0,
          "scan_status": "running",
          "audited_urls": 1,
          "queued_pages": 0,
          "audited_pages": 1,
          "request_count": 2634,
          "response_time": 0
        },
        "scanner": {
          "group_name": "US Cloud Scanner"
        },
        "template_name": "scan"
      },
      "user_template": null
    },
    {
      "config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
      "owner_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
      "is_shared": false,
      "user_permissions": "configure",
      "name": "Example 2",
      "target": "http://192.0.2.119",
      "description": null,
      "created_at": "2020-02-05T23:16:11.883Z",
      "updated_at": "2020-02-05T23:16:11.883Z",
      "schedule": null,
      "template_id": "112f3e7f-d83a-4bba-b2c8-df2d22e2fa4c",
      "last_scan": {
        "scan_id": "934848fa-2e28-4f1e-a438-dcbeef89b5b5",
        "user_id": "4a0d43eb-77e2-4a52-b24a-93d29bcb0aba",
        "config_id": "a3775500-38f4-4cb1-b032-5386b445e554",
        "asset_id": "22807f4e-d678-4c60-bcb9-6af2a0623f9b",
        "target": "http://192.0.2.119",
        "application_uri": "http://192.0.2.119",
        "created_at": "2020-02-19T16:52:17.264Z",
        "updated_at": "2020-02-19T16:55:59.154Z",
        "started_at": null,
        "finalized_at": null,
        "requested_action": "start",
        "status": "aborted",
        "metadata": {
          "estimate_crawl_percent_complete": 100,
          "queued_urls": 0,
          "scan_status": "running",
          "crawled_urls": 11,
          "queued_pages": 0,
          "audited_pages": 18,
          "request_count": 678,
          "response_time": 0
        },
        "scanner": null,
        "template_name": "overview"
      },
      "user_template": null
    }
  ]
}