Skip to content

Retrieve tasks

GET/tasks

Switch Management API · Tasks

Get task details for the tenant.

Required permissioncswitch.config:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
page query integer No The page number to fetch, starting with 1.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
pageSize query integer No The size of the page requested.
Must be ≥ 1 and ≤ 500.
type query string No Type of the policy to filter the tasks.
fields query array of string No Fields to be retrieved for task.
Each item must be one of: switches.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/switch/v1/tasks" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/switch/v1/tasks",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/switch/v1/tasks" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/switch/v1/tasks", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/switch/v1/tasks", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Task settings retrieved successfully.

Response fields

itemsarray of objectrequired
List of tasks.
Items must be unique.
List of tasks for the tenant.
Show child attributesHide child attributes
idstring (uuid)required
UUID of the Task.
typestringrequired
Type of the policy, valid values are macFilter, vlan.
tenantobjectrequired
Tenant ID.
Show child attributesHide child attributes
idstring (uuid)required
Tenant ID.
createdByobject
Principal reference.
Show child attributesHide child attributes
idstringrequired
Principal email or client ID.
typestring (enum)required
Principal type.
Must be one of: user, service.
accountTypestring
Account type.
Must be one of: partner, tenant, organization.
accountIdstring (uuid)
Account ID.
createdAtstring (date-time)
Timestamp when the task is created.
updatedByobject
Principal reference.
Show child attributesHide child attributes
idstringrequired
Principal email or client ID.
typestring (enum)required
Principal type.
Must be one of: user, service.
accountTypestring
Account type.
Must be one of: partner, tenant, organization.
accountIdstring (uuid)
Account ID.
updatedAtstring (date-time)
Timestamp when the task is updated.
statusobjectrequired
Task status statistics for the switches.
Show child attributesHide child attributes
succeededintegerrequired
Number of switches with successfully synchronized task.
failedintegerrequired
Number of switches with failed synchronized task.
pendingintegerrequired
Number of switches with pending synchronized task.
noSupportSubscriptionintegerrequired
Number of switches where a task isn't synchronised due to a missing or invalid support subscription.
totalintegerrequired
Number of switches for which a task is generated.
switchesarray of object
List of switches with status.
Task status statistics for the switches.
Show child attributesHide child attributes
idstring (uuid)required
UUID of the Switch.
statusstringrequired
Task status.
Must be one of: succeeded, failed, pending, noSupportSubscription.
errorobject
Show child attributesHide child attributes
errorstring
messagestringrequired
codestring
docUrlstring (uri)
pagesobjectrequired
Show child attributesHide child attributes
currentintegerrequired
The 1-based page number being returned.
sizeintegerrequired
The size of the page being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items across all pages.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
400 Bad request.
401 Authentication required.
403 Authorization required.
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    {
      "id": "687079a8-4249-4933-9ac6-2d701b4107ff",
      "type": "macFilter",
      "tenant": {
        "id": "3e382b8e-49fd-4cd9-8360-a364371d7650"
      },
      "createdBy": {
        "id": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "type": "user",
        "accountId": "3e382b8e-49fd-4cd9-8360-a364371d7650",
        "accountType": "tenant"
      },
      "createdAt": "2022-03-30T05:43:59.492",
      "updatedBy": {
        "id": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "type": "user",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8",
        "accountType": "tenant"
      },
      "updatedAt": "2022-03-30T05:43:59.492",
      "status": {
        "succeeded": 1,
        "failed": 1,
        "pending": 1,
        "noSupportSubscription": 1,
        "total": 4
      },
      "switches": [
        {
          "id": "5519e706-a704-4a42-9a3a-282aa4e336c5",
          "status": "succeeded"
        },
        {
          "id": "867df519-f483-41f3-9799-30d3b6d926e0",
          "status": "failed",
          "error": {
            "error": "badRequest",
            "message": "The MAC address filter already exists",
            "code": "10905",
            "docUrl": "https://developer.sophos.com/switch-management#switch-error-codes"
          }
        },
        {
          "id": "3b6c8fc1-2745-4382-b20a-e57f19171403",
          "status": "pending"
        },
        {
          "id": "8c7e74f0-61fb-4d7d-9057-c072c163432f",
          "status": "noSupportSubscription"
        }
      ]
    },
    {
      "id": "2d90a679-5bac-4e45-a5f3-b62c78c08b24",
      "type": "vlan",
      "tenant": {
        "id": "3e382b8e-49fd-4cd9-8360-a364371d7650"
      },
      "createdBy": {
        "id": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "type": "user",
        "accountId": "3e382b8e-49fd-4cd9-8360-a364371d7650",
        "accountType": "tenant"
      },
      "createdAt": "2022-03-30T05:43:59.492",
      "updatedBy": {
        "id": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "type": "user",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8",
        "accountType": "tenant"
      },
      "updatedAt": "2022-03-30T05:43:59.492",
      "status": {
        "succeeded": 1,
        "failed": 0,
        "pending": 0,
        "noSupportSubscription": 0,
        "total": 1
      },
      "switches": [
        {
          "id": "5519e706-a704-4a42-9a3a-282aa4e336c5",
          "status": "succeeded"
        }
      ]
    }
  ],
  "pages": {
    "current": 1,
    "total": 1,
    "items": 1,
    "size": 100,
    "maxSize": 1000
  }
}

See the guide for a narrative walkthrough of this API.