API reference - Amazon Managed Service for Prometheus
Amazon Managed Service for Prometheus APIsPrometheus-compatible APIs

API reference

This section lists the API operations and data structures supported by Amazon Managed Service for Prometheus.

For information about these API operations and their quotas for series, labels, and API requests, see Amazon Managed Service for Prometheus service quotas in the Amazon Managed Service for Prometheus User Guide.

Amazon Managed Service for Prometheus APIs

The following Amazon Managed Service for Prometheus API operations and data structures are supported.

CreateAlertManagerDefinition

The CreateAlertManagerDefinition operation creates the alert manager definition in a workspace. If a workspace already has an alert manager definition, don't use this operation to update it. Instead, use PutAlertManagerDefinition.

The data parameter contains the base64-encoded version of the YAML alert manager definition file.

Request parameters

  • workspaceId—The ID of the workspace to add the alert manager definition to.

  • data— The alert manager definition to add. This is an AlertManagerDefinitionData structure.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

Sample request

POST /workspaces HTTP/1.1
Content-Length: 415, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
    "clientToken": "64111b4d-0e57-4487-9bee-570709c37699"
}

Sample response

HTTP/1.1 202 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 36
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "status": {
        "statusCode": "CREATING"
    }
}

CreateRuleGroupsNamespace

The CreateRuleGroupsNamespace operation creates a rule groups namespace within a workspace. A rule groups namespace is associated with exactly one rules file. A workspace can have multiple rule groups namespaces.

Use this operation only to create new rule groups namespaces. To update an existing rule groups namespace, use PutRuleGroupsNamespace.

The data parameter contains the base64-encoded version of the YAML rules file.

Request parameters

  • workspaceId—The ID of the workspace to add the rule groups namespace.

  • name—The name for the new rule groups namespace.

  • data— The rules file to use in the new namespace. This is a RuleGroupsNamespaceData structure.

  • tags— (Optional) The list of tag keys and values to associate with the rule groups namespace.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • name—The name of the new rule groups namespace.

  • status—A structure that displays the current status of the rule groups namespace. For more information, see RuleGroupsNamespaceStatus structure.

  • arn—The Amazon Resource Name (ARN) of the new rule groups namespace.

  • tags— The list of tag keys and values that are associated with the namespace.

Sample request

POST /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/rulegroupsnamespaces HTTP/1.1
Content-Length: 253
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
    "name": "test-rules",
    "clientToken": "64111b4d-0e57-4487-9bee-570709c37699"
}

Sample response

HTTP/1.1 202 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 212
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "arn": "arn:aws:aps:us-west-2:123456789012:rulegroupsnamespace/ws-b226cc2a-a446-46a9-933a-ac50479a5568/test-rules",
    "name": "test-rules",
    "status": {
        "statusCode": "CREATING"
    },
    "tags": {}
}

CreateWorkspace

The CreateWorkspace operation creates a workspace. A workspace is a logical space dedicated to the storage and querying of Prometheus metrics. You can have one or more workspaces in each Region in your account.

Request parameters

  • alias—(Optional) An alias that you assign to this workspace to help you identify it. It does not need to be unique.

    The alias can be up to 100 characters and can include any type of characters. Amazon Managed Service for Prometheus will automatically strip any blank spaces from the beginning and end of the alias that you specify.

  • tags— (Optional) The list of tag keys and values to associate with the workspace.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • workspaceId—The unique ID for the new workspace.

  • arn—The ARN for the new workspace.

  • tags— (Optional) The list of tag keys and values that are associated with the workspace.

  • status—The current status of the new workspace. Immediately after you create the workspace, the status is usually CREATING.

Sample request

POST /workspaces HTTP/1.1
Content-Length: 79, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "alias": "myWorkspace",
    "tags": { 
       "Status": "Secret",
       "Team": "My-Team"
   },
    "clientToken": "6e5b2726-4bb0-4010-a2e3-de91980cf783"
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 185
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "arn": "arn:aws:aps:us-west-2:123456789012:workspace/ws-12345678-1234-46a9-933a-ac50479a5568",
    "status": {
        "statusCode": "CREATING"
    },
    "tags": { 
       "Status": "Secret",
       "Team": "My-Team"
   },
    "workspaceId": "ws-b226cc2a-a446-46a9-933a-ac50479a5568"
}

DeleteAlertManagerDefinition

The DeleteAlertManagerDefinition operation deletes the alert manager definition from a workspace.

Request parameters

  • workspaceId— The ID of the workspace to delete the alert manager definition from.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • None

Sample request

DELETE /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/definition HTTP/1.1
Content-Length: 61, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "clientToken": "64111b4d-0e57-4487-9bee-570709c37699"
}

Sample response

tion/x-amz-json-1.1

DeleteRuleGroupsNamespace

The DeleteRuleGroupsNamespace operation deletes one rule groups namespace and its associated rule groups definition.

Request parameters

  • workspaceId—The ID of the workspace containing the rule groups namespace and definition to delete.

  • name—The name of the rule groups namespace to delete.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • None

Sample request

DELETE /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/rulegroupsnamespaces/test-rules HTTP/1.1
Content-Length: 61, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "clientToken": "b371aa96-a5ef-455d-9561-f4b2b8cb0c5c"
}

Sample response

HTTP/1.1 202 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 0
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

DeleteWorkspace

The DeleteWorkspace operation deletes an existing workspace.

When you delete a workspace, the data that has been ingested into it is not immediately deleted. It will be permanently deleted within one month.

Request parameters

  • workspaceId—The ID of the workspace to delete.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • None

Sample request

DELETE /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568?clientToken=99ce509d-014c-4911-8f71-9844d9df0a97 HTTP/1.1
Content-Length: 79, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "alias": "myWorkspace",
    "clientToken": "6e5b2726-4bb0-4010-a2e3-de91980cf783"
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 185
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

DescribeAlertManagerDefinition

The DescribeAlertManagerDefinition operation retrieves the full information about the alert manager definition for one workspace.

Request parameters

  • workspaceId—The ID of the workspace to retrieve the alert manager definition from.

Response elements

Sample request

Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 480
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "alertManagerDefinition": {
        "createdAt": 1.635198605029E9,
        "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
        "modifiedAt": 1.635198666202E9,
        "status": {
            "statusCode": "ACTIVE",
            "statusReason": ""
        }
    }
}

DescribeRuleGroupsNamespace

The DescribeRuleGroupsNamespace operation returns complete information about one rule groups namespace. To retrieve a list of rule groups namespaces, use ListRuleGroupsNamespaces.

Request parameters

  • workspaceId—The ID of the workspace containing the rule groups namespace.

  • name—The name of the rule groups namespace that you want information for.

Response elements

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/rulegroupsnamespaces/test-rules HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 519
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "ruleGroupsNamespace": {
        "arn": "arn:aws:aps:us-west-2:123456789012:rulegroupsnamespace/ws-12345678-a446-46a9-933a-ac50479a5568/test-rules",
        "createdAt": 1.63485026039E9,
        "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
        "modifiedAt": 1.63485027191E9,
        "name": "test-rules",
        "status": {
            "statusCode": "ACTIVE",
            "statusReason": ""
        },
        "tags": {}
    }
}

DescribeWorkspace

The DescribeWorkspace operation displays information about an existing workspace.

Request parameters

  • workspaceId—The ID of the workspace to describe.

Response elements

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568 HTTP/1.1
Content-Length: 79, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "alias": "myWorkspace",
    "clientToken": "6e5b2726-4bb0-4010-a2e3-de91980cf783"
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 185
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "workspace": {
        "alias": "myWorkspace",
        "arn": "arn:aws:aps:us-west-2:123456789012:workspace/ws-12345678-a446-46a9-933a-ac50479a5568",
        "createdAt": 1.606851445922E9,
        "prometheusEndpoint": "https://aps-workspaces.us-west-2.amazonaws.com/workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/",
        "status": {
            "statusCode": "ACTIVE"
        },
        "tags": { 
         "Status": "Secret",
         "Team": "My-Team"
     },
        "workspaceId": "ws-12345678-a446-46a9-933a-ac50479a5568"
    }
}

ListRuleGroupsNamespaces

The ListRuleGroupsNamespaces operation returns a list of rule groups namespaces in a workspace.

Request parameters

  • workspaceId—The ID of the workspace containing the rule groups namespaces.

  • name—(Optional) Use this parameter to filter the rule groups namespaces that are returned. Only the namespaces with names that begin with the value that you specify are returned.

  • maxResults— (Optional) The maximum number of results to return. Valid values are 1–1000. The default is 100.

  • nextToken—(Optional) The token for the next set of items to return. (You received this token from a previous call.)

Response elements

  • ruleGroupsNamespaces— The returned list of rule groups namespaces. Each item in the list is a RuleGroupsNamespaceSummary structure.

  • nextToken—A token indicating that there are more results to retrieve. You can use this token as part of your next ListRuleGroupsNamespaces operation to retrieve those results.

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/rulegroupsnamespaces HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 359
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "ruleGroupsNamespaces": [
        {
            "arn": "arn:aws:aps:us-west-2:123456789012:rulegroupsnamespace/ws-b226cc2a-a446-46a9-933a-ac50479a5568/test-rules",
            "createdAt": 1.63485026039E9,
            "modifiedAt": 1.634850638181E9,
            "name": "test-rules",
            "status": {
                "statusCode": "ACTIVE",
                "statusReason": ""
            },
            "tags": {}
        }
    ]
}

ListTagsForResource

The ListTagsForResource operation returns the tags that are associated with an Amazon Managed Service for Prometheus resource. Currently, the only resource that can be tagged is a workspace.

Request parameters

  • resourceArn—The ARN of the workspace.

Response elements

  • tags—The list of tag keys and values associated with the resource.

Sample request

GET /tags/arn%3Aaws%3Aaps%3Aus-east-2%3A621014813884%3Aworkspace%2Fws-effda945-fb72-4e8b-bbb7-c0ca7e72d5b6 HTTP/1.1
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "resourceArn": ""arn:aws:aps:us-west-2:123456789012:workspace/ws-12345678-a446-46a9-933a-ac50479a5568"",
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 43
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "tags": {
        "Status": "Secret",
        "Team": "My-Team"
    }
}

ListWorkspaces

The ListWorkspaces operation lists all of the Amazon Managed Service for Prometheus workspaces in your account. This includes workspaces being created or deleted.

Request parameters

  • alias—(Optional) If this is included, it filters the results to only the workspaces with names that start with the value that you specify here.

    Amazon Managed Service for Prometheus will automatically strip any blank spaces from the beginning and end of the alias that you specify.

  • maxResults—(Optional) The maximum number of workspaces to return in one ListWorkspaces operation. The range is 1–1000.

    If you omit this parameter, the default of 100 is used.

  • nextToken—(Optional) The token for the next set of items to return. (You received this token from a previous call.)

Response elements

  • workspaces—An array of WorkspaceSummary structures. For more information, see WorkspaceSummary structure.

  • nextToken—A token indicating that there are more results to retrieve. You can use this token as part of your next ListWorkspaces operation to retrieve those results.

Sample request

GET /workspaces?alias=myWorkspace HTTP/1.1
Content-Length: 79, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "alias": "myWorkspace",
    "tags": {
        "Status": "Secret",
        "Team": "My-Team"
    },
    "clientToken": "6e5b2726-4bb0-4010-a2e3-de91980cf783"
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 185
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "nextToken": null,
    "workspaces": [
        {
            "alias": "myWorkspace",
            "arn": "arn:aws:aps:us-west-2:123456789012:workspace/ws-b226cc2a-a446-46a9-933a-ac50479a5568",
            "createdAt": 1.606851445922E9,
            "status": {
                "statusCode": "ACTIVE"
            },
            "workspaceId": "ws-12345678-a446-46a9-933a-ac50479a5568" 
        }
    ]
}

PutAlertManagerDefinition

The PutAlertManagerDefinition operation updates an existing alert manager definition in a workspace. If a workspace does not already have an alert manager definition, don't use this operation to create it. Instead, use CreateAlertManagerDefinition.

Request parameters

  • workspaceId—The ID of the workspace to update the alert manager definition in.

  • data— The new alert manager definition to use. This is an AlertManagerDefinitionData structure.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

Sample request

PUT /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/definition HTTP/1.1
Content-Length: 409, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
    "clientToken": "6495e935-b4ec-4c39-a8ac-37fb99973589"
}

Sample response

HTTP/1.1 202 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 185
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

{
    "alertManagerDefinition": {
        "createdAt": 1.634848225614E9,
        "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
        "modifiedAt": 1.63484828633E9,
        "status": {
            "statusCode": "ACTIVE",
            "statusReason": ""
        }
    }
}

PutRuleGroupsNamespace

The PutRuleGroupsNamespace operation updates an existing rule groups namespace within a workspace. A rule groups namespace is associated with exactly one rules file. A workspace can have multiple rule groups namespaces.

Use this operation only to update existing rule groups namespaces. To create a new rule groups namespace, use CreateRuleGroupsNamespace.

You can't use this operation to add tags to an existing rule groups namespace. Instead, use TagResource.

Request parameters

  • workspaceId—The ID of the workspace where you are updating the rule groups namespace.

  • name—The name of the rule groups namespace that you are updating.

  • data— The new rules file to use in the namespace. This is a RuleGroupsNamespaceData structure.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • name—The name of the new rule groups namespace.

  • status—A structure that displays the current status of the rule groups namespace. For more information, see RuleGroupsNamespaceStatus structure.

  • arn—The ARN of the rule groups namespace.

  • tags— The list of tag keys and values that are associated with the namespace.

Sample request

PUT /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/rulegroupsnamespaces/test-rules HTTP/1.1
Content-Length: 225, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "data": "EXAMPLE2NvbmZpZzogfAogIGdsb2Jhb...",
    "clientToken": "1b1ef402-b1bc-4f86-8560-7ce0a45c32d6"
}

Sample response

   "tags": {}
}

TagResource

The TagResource operation associates tags with an Amazon Managed Service for Prometheus resource. Currently, the only resources that can be tagged are workspaces and rule groups namespaces.

If you specify a new tag key for the resource, this tag is appended to the list of tags associated with the resource. If you specify a tag key that is already associated with the resource, the new tag value that you specify replaces the previous value for that tag.

Request parameters

  • resourceArn—The ARN of the workspace or rule groups namespace to apply tags to.

  • tags—The list of tag keys and values to associate with the resource.

Response elements

If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Sample request

POST /tags/arn%3Aaws%3Aaps%3Aus-east-2%31234567893884%3Aworkspace%2Fws-effda945-fb72-4e8b-bbb7-1234567895b6 HTTP/1.1
Content-Type: application/json

X-Amz-Date: 20210829T223002Z
Authorization: AUTHPARAMS
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "resourceArn": "arn:aws:aps:us-west-2:123456789012:workspace/ws-12345678-a446-46a9-933a-ac50479a5568",
    "tags": { 
       "Status": "Secret",
       "Team": "My-Team"
   }
}

Sample response

HTTP/1.1 204 No Content
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 0
Content-Type: application/x-amz-json-1.1

UntagResource

The UntagResource operation removes the specified tags from an Amazon Managed Service for Prometheus resource. Currently, the only resources that can be tagged are workspaces and rule groups namespaces.

Request parameters

  • resourceArn—The ARN of the workspace or rule groups namespace.

  • tagKeys—The keys of the tags to remove.

Response elements

If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Sample request

DELETE /tags/arn:aws:aps:us-west-2:123456789012:workspace/ws-12345678-a446-46a9-933a-ac50479a5568?tagKeys=myNewTag HTTP/1.1
Content-Type: application/json
X-Amz-Date: 20210829T223002Z
Authorization: AUTHPARAMS
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

Sample response

HTTP/1.1 204 No Content
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 0
Content-Type: application/x-amz-json-1.1

UpdateWorkspaceAlias

The UpdateWorkspaceAlias operation updates the alias of an existing workspace.

Request parameters

  • workspaceId—The ID of the workspace to update.

  • alias—The new alias for the workspace. It does not need to be unique.

    The alias can be up to 100 characters and can include any type of characters. Amazon Managed Service for Prometheus will automatically strip any blank spaces from the beginning and end of the alias that you specify.

  • clientToken—(Optional) A unique, case-sensitive identifier that you can provide to ensure the idempotency of the request.

Response elements

  • None

Sample request

POST /workspaces/ws-1234567890-a446-46a9-933a-ac50479a5568/alias HTTP/1.1
Content-Length: 79, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: aws-cli/1.18.147 Python/2.7.18 Linux/5.4.58-37.125.amzn2int.x86_64 botocore/1.18.6

{
    "alias": "myWorkspace",
    "clientToken": "6e5b2726-4bb0-4010-a2e3-de91980cf783"
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 185
Access-Control-Allow-Methods: OPTION,GET,POST,DELETE
Access-Control-Expose-Headers: x-amzn-errortype,x-amzn-requestid,x-amzn-trace-id,x-amzn-errormessage,x-amz-apigw-id,date
Strict-Transport-Security: strict-transport-security: max-age=31536000; includeSubDomains
x-amz-apigw-id: 1234EXAMPLE=
X-Amzn-Trace-Id: Root=1-12345678-39c98b574fd600282a1a0f21
Connection: keep-alive
Cache-Control: no-store,no-cache,must-revalidate
Date: Tue, 01 Dec 2020 19:37:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *,Authorization,Date,X-Amz-Date,content-type,x-amz-content-sha256,x-amz-user-agent,x-amzn-platform-id,x-amzn-trace-id,X-Amz-Security-Token,X-Amz-Target
Content-Type: application/x-amz-json-1.1

AlertManagerDefinitionData structure

The AlertManagerDefinitionData structure contains the actual alert manager definition as a blob (binary data). It is a base64-encoded YAML file. The following is an example of an alert manager configuration file YAML.

alertmanager_config: |
  route:
    receiver: 'default'
  receivers:
    - name: 'default'
      sns_configs:
      - topic_arn: arn:aws:sns:us-east-2:123456789012:My-Topic
        sigv4:
          region: us-east-2
        attributes:
          key: key1
          value: value1

AlertManagerDefinitionDescription structure

The AlertManagerDefinitionDescription structure contains the full details about one alert manager definition.

Structure parameters

  • alertManagerDefinitionData—The actual alert manager definition.

  • alertManagerDefinitionStatus—A structure that displays the current status of the alert manager definition. For more information, see AlertManagerDefinitionStatus structure.

  • createdAt—The date and time that the alert manager definition was created.

  • modifiedAt—The date and time that the alert manager definition was most recently changed.

AlertManagerDefinitionStatus structure

The AlertManagerDefinitionStatus structure displays status information about the alert manager.

Structure parameters

  • statusCode—The current status of the alert manager.

  • statusReason—The reason for the failure, if any.

RuleGroupsNamespaceData structure

The RuleGroupsNamespaceData structure contains the rule groups file as a base64-encoded blob of the YAML file. The following is an example of an rules file YAML.

groups:
  - name: test
    rules:
    - record: metric:recording_rule
      expr: avg(rate(container_cpu_usage_seconds_total[5m]))
  - name: alert-test
    rules:
    - alert: metric:alerting_rule
      expr: avg(rate(container_cpu_usage_seconds_total[5m])) > 0
      for: 2m

RuleGroupsNamespaceDescription structure

The RuleGroupsNamespaceDescription structure contains the full details about one rule groups namespace.

Structure parameters

  • name—The name of the rule groups namespace.

  • arn—The ARN of the rule groups namespace.

  • status—A structure that displays the current status of the rule groups namespace. For more information, see RuleGroupsNamespaceStatus structure.

  • RuleGroupsNamespaceData—The rule groups file used in the namespace.

  • createdAt—The date and time that the rule groups namespace was created.

  • modifiedAt—The date and time that the rule groups namespace was most recently changed.

  • tags— (Optional) The list of tag keys and values that are associated with the rule groups namespace.

RuleGroupsNamespaceStatus structure

The RuleGroupsNamespaceStatus structure displays status information about the rule groups namespace.

Structure parameters

  • statusCode—The current status of the namespace. The possible values are CREATING, ACTIVE, UPDATING, DELETING, CREATION_FAILED, and UPDATE_FAILED.

  • statusReason—The reason for the failure, if any.

RuleGroupsNamespaceSummary structure

The RuleGroupsNamespaceSummary structure contains some information about one rule groups namespace. To retrieve more information about one rule groups namespace, use DescribeRuleGroupsNamespace.

Structure parameters

  • name—The name of the rule groups namespace.

  • arn—The ARN of the rule groups namespace.

  • status—A structure that displays the current status of the rule groups namespace. For more information, see RuleGroupsNamespaceStatus structure.

  • createdAt—The date and time that the rule groups namespace was created.

  • modifiedAt—The date and time that the rule groups namespace was most recently changed.

  • tags— (Optional) The list of tag keys and values that are associated with the rule groups namespace.

WorkspaceDescription structure

The WorkspaceDescription structure contains the full details about one Amazon Managed Service for Prometheus workspace in your account.

Structure parameters

  • workspaceId—The unique ID for the workspace.

  • arn—The ARN of the workspace.

  • status—The current status of the workspace. The possible values are CREATING, ACTIVE, UPDATING, DELETING, and CREATION_FAILED.

  • prometheusEndpoint—The Prometheus endpoint available for this workspace.

  • createdAt—The date and time that the workspace was created.

  • tags— (Optional) The list of tag keys and values that are associated with the workspace.

WorkspaceSummary structure

The WorkspaceSummary structure contains information about one Amazon Managed Service for Prometheus workspace in your account.

Structure parameters

  • workspaceId—The unique ID for the workspace.

  • arn—The ARN of the workspace.

  • status—The current status of the workspace. The possible values are CREATING, ACTIVE, UPDATING, DELETING, and CREATION_FAILED.

  • createdAt—The date and time that the workspace was created.

  • tags— (Optional) The list of tag keys and values that are associated with the workspace.

Common errors

This section lists the errors common to the API actions of all AWS services. For errors specific to an API action for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400

IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400

InternalFailure

The request processing has failed because of an unknown error, exception, or failure.

HTTP Status Code: 500

InvalidAction

The action or operation requested is not valid. Verify that the action is typed correctly.

HTTP Status Code: 400

InvalidClientTokenId

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403

InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400

InvalidParameterValue

The supplied value for the input parameter is not valid or is out-of-range.

HTTP Status Code: 400

InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400

MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404

MissingAction

The request is missing an action or a required parameter.

HTTP Status Code: 400

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

HTTP Status Code: 403

MissingParameter

A required parameter for the specified action is not supplied.

HTTP Status Code: 400

NotAuthorized

You do not have permission to perform this action.

HTTP Status Code: 400

OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403

RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for presigned URLs), or the date stamp on the request is more than 15 minutes in the future.

HTTP Status Code: 400

ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

ValidationError

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

Prometheus-compatible APIs

Amazon Managed Service for Prometheus supports the following Prometheus-compatible APIs.

For more information about using Prometheus-compatible APIs, see Query using Prometheus-compatible APIs in this guide.

CreateAlertManagerAlerts

The CreateAlertManagerAlerts operation creates an alert in the workspace.

Valid HTTP verbs:

POST

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/alerts

URL query parameters:

alerts An array of objects, where each object represents one alert. The following is an example of an alert object:

[
  {
    "startsAt": "2021-09-24T17:14:04.995Z",
    "endsAt": "2021-09-24T17:14:04.995Z",
    "annotations": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "labels": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "generatorURL": "string"
  }
]

Sample request

POST /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/alerts HTTP/1.1
Content-Length: 203, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

[
  {
    "labels": {
      "alertname": "test-alert"
    },
    "annotations": {
      "summary": "this is a test alert used for demo purposes"
    },
    "generatorURL": "https://www.amazon.com/"
  }
]

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 0
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

DeleteAlertManagerSilence

The DeleteSilence deletes one alert silence.

Valid HTTP verbs:

DELETE

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/silence/silenceID

URL query parameters: none

Sample request

DELETE /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/silence/d29d9df3-9125-4441-912c-70b05f86f973 HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 0
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

GetAlertManagerStatus

The GetAlertManagerStatus retrieves information about the status of alert manager.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/status

URL query parameters: none

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/status HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 941
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
    "cluster": null,
    "config": {
        "original": "global:\n  resolve_timeout: 5m\n  http_config:\n    follow_redirects: true\n  smtp_hello: localhost\n  smtp_require_tls: true\nroute:\n  receiver: sns-0\n  group_by:\n  - label\n  continue: false\nreceivers:\n- name: sns-0\n  sns_configs:\n  - send_resolved: false\n    http_config:\n      follow_redirects: true\n    sigv4: {}\n    topic_arn: arn:aws:sns:us-west-2:123456789012:test\n    subject: '{{ template \"sns.default.subject\" . }}'\n    message: '{{ template \"sns.default.message\" . }}'\n    workspace_arn: arn:aws:aps:us-west-2:123456789012:workspace/ws-58a6a446-5ec4-415b-9052-a449073bbd0a\ntemplates: []\n"
    },
    "uptime": null,
    "versionInfo": null
}

GetAlertManagerSilence

The GetAlertManagerSilence retrieves information about one alert silence.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/silence/silenceID

URL query parameters: none

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/silence/d29d9df3-9125-4441-912c-70b05f86f973 HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 310
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
    "id": "d29d9df3-9125-4441-912c-70b05f86f973",
    "status": {
        "state": "active"
    },
    "updatedAt": "2021-10-22T19:32:11.763Z",
    "comment": "hello-world",
    "createdBy": "test-person",
    "endsAt": "2023-07-24T01:05:36.000Z",
    "matchers": [
        {
            "isEqual": true,
            "isRegex": true,
            "name": "job",
            "value": "hello"
        }
    ],
    "startsAt": "2021-10-22T19:32:11.763Z"
}

GetLabels

The GetLabels operation retrieves the labels associated with a time series.

Valid HTTP verbs:

GET, POST

Valid URIs:

/workspaces/workspaceId/api/v1/labels

/workspaces/workspaceId/api/v1/label/label-name/values This URI supports only GET requests.

URL query parameters:

match[]=<series_selector> Repeated series selector argument that selects the series from which to read the label names. Optional.

start=<rfc3339 | unix_timestamp> Start timestamp. Optional.

end=<rfc3339 | unix_timestamp> End timestamp. Optional.

Sample request for /workspaces/workspaceId/api/v1/labels

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/labels HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response for /workspaces/workspaceId/api/v1/labels

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 1435
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
    "status": "success",
    "data": [
        "__name__",
        "access_mode",
        "address",
        "alertname",
        "alertstate",
        "apiservice",
        "app",
        "app_kubernetes_io_instance",
        "app_kubernetes_io_managed_by",
        "app_kubernetes_io_name",
        "area",
        "beta_kubernetes_io_arch",
        "beta_kubernetes_io_instance_type",
        "beta_kubernetes_io_os",
        "boot_id",
        "branch",
        "broadcast",
        "buildDate",
        ...
    ]
}

Sample request for /workspaces/workspaceId/api/v1/label/label-name/values

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/label/access_mode/values HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response for /workspaces/workspaceId/api/v1/label/label-name/values

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 74
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
    "status": "success",
    "data": [
        "ReadWriteOnce"
    ]
}

GetMetricMetadata

The GetMetricMetadata operation retrieves metadata about metrics that are currently being scraped from targets. It does not provide any target information.

The data section of the query result consists of an object where each key is a metric name and each value is a list of unique metadata objects, as exposed for that metric name across all targets.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/api/v1/metadata

URL query parameters:

limit=<number> The maximum number of metrics to return.

metric=<string> A metric name to filter metadata for. If you keep this empty, all metric metadata is retrieved.

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/metadata HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
Transfer-Encoding: chunked

{
    "status": "success",
    "data": {
        "aggregator_openapi_v2_regeneration_count": [
            {
                "type": "counter",
                "help": "[ALPHA] Counter of OpenAPI v2 spec regeneration count broken down by causing APIService name and reason.",
                "unit": ""
            }
        ],
        ...
    }
}

GetSeries

The GetSeries operation retrieves list of time series that match a certain label set.

Valid HTTP verbs:

GET, POST

Valid URIs:

/workspaces/workspaceId/api/v1/series

URL query parameters:

match[]=<series_selector> Repeated series selector argument that selects the series to return. At least one match[] argument must be provided.

start=<rfc3339 | unix_timestamp> Start timestamp. Optional

end=<rfc3339 | unix_timestamp> End timestamp. Optional

Sample request

POST /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/series --data-urlencode 'match[]=node_cpu_seconds_total{app="prometheus"}' --data-urlencode 'start=1634936400' --data-urlencode 'end=1634939100' HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
content-encoding: gzip

{
    "status": "success",
    "data": [
        {
            "__name__": "node_cpu_seconds_total",
            "app": "prometheus",
            "app_kubernetes_io_managed_by": "Helm",
            "chart": "prometheus-11.12.1",
            "cluster": "cluster-1",
            "component": "node-exporter",
            "cpu": "0",
            "heritage": "Helm",
            "instance": "10.0.100.36:9100",
            "job": "kubernetes-service-endpoints",
            "kubernetes_name": "servicesstackprometheuscf14a6d7-node-exporter",
            "kubernetes_namespace": "default",
            "kubernetes_node": "ip-10-0-100-36.us-west-2.compute.internal",
            "mode": "idle",
            "release": "servicesstackprometheuscf14a6d7"
        },
        {
            "__name__": "node_cpu_seconds_total",
            "app": "prometheus",
            "app_kubernetes_io_managed_by": "Helm",
            "chart": "prometheus-11.12.1",
            "cluster": "cluster-1",
            "component": "node-exporter",
            "cpu": "0",
            "heritage": "Helm",
            "instance": "10.0.100.36:9100",
            "job": "kubernetes-service-endpoints",
            "kubernetes_name": "servicesstackprometheuscf14a6d7-node-exporter",
            "kubernetes_namespace": "default",
            "kubernetes_node": "ip-10-0-100-36.us-west-2.compute.internal",
            "mode": "iowait",
            "release": "servicesstackprometheuscf14a6d7"
        },
        ...
    ]
}

ListAlerts

The ListAlerts operation retrieves currently active alerts in the workspace.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/api/v1/alerts

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/alerts HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 386
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
  "status": "success",
  "data": {
    "alerts": [
      {
        "labels": {
          "alertname": "test-1.alert",
          "severity": "none"
        },
        "annotations": {
          "message": "message"
        },
        "state": "firing",
        "activeAt": "2020-12-01T19:37:25.429565909Z",
        "value": "1e+00"
      }
    ]
  },
  "errorType": "",
  "error": ""
}

ListAlertManagerAlerts

The ListAlertManagerAlerts retrieves information about the alerts currently firing in alert manager in the workspace.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/alerts

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/alerts HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 354
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

[
    {
        "annotations": {
            "summary": "this is a test alert used for demo purposes"
        },
        "endsAt": "2021-10-21T22:07:31.501Z",
        "fingerprint": "375eab7b59892505",
        "receivers": [
            {
                "name": "sns-0"
            }
        ],
        "startsAt": "2021-10-21T22:02:31.501Z",
        "status": {
            "inhibitedBy": [],
            "silencedBy": [],
            "state": "active"
        },
        "updatedAt": "2021-10-21T22:02:31.501Z",
        "labels": {
            "alertname": "test-alert"
        }
    }
]

ListAlertManagerAlertGroups

The ListAlertManagerAlertGroups operation retrieves a list of alert groups configured in alert manager in the workspace.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/alerts/groups

URL query parameters:

active Boolean. If true, the returned list includes active alerts. The default is true. Optional

silenced Boolean. If true, the returned list includes silenced alerts. The default is true. Optional

inhibited Boolean. If true, the returned list includes inhibited alerts. The default is true. Optional

filter An array of strings. A list of matchers to filter alerts by. Optional

receiver String. A regular expression matching receivers to filter alerts by. Optional

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/alerts/groups HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 443
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

[
    {
        "alerts": [
            {
                "annotations": {
                    "summary": "this is a test alert used for demo purposes"
                },
                "endsAt": "2021-10-21T22:07:31.501Z",
                "fingerprint": "375eab7b59892505",
                "receivers": [
                    {
                        "name": "sns-0"
                    }
                ],
                "startsAt": "2021-10-21T22:02:31.501Z",
                "status": {
                    "inhibitedBy": [],
                    "silencedBy": [],
                    "state": "unprocessed"
                },
                "updatedAt": "2021-10-21T22:02:31.501Z",
                "generatorURL": "https://www.amazon.com/",
                "labels": {
                    "alertname": "test-alert"
                }
            }
        ],
        "labels": {},
        "receiver": {
            "name": "sns-0"
        }
    }
]

ListAlertManagerReceivers

The ListAlertManagerReceivers operation retrieves information about the receivers configured in alert manager.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/receivers

URL query parameters: none

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/receivers HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 19
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

[
    {
        "name": "sns-0"
    }
]

ListAlertManagerSilences

The ListAlertManagerSilences operation retrieves information about the alert silences configured in the workspace.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/silences

Sample request

GET /workspaces/ws-58a6a446-5ec4-415b-9052-a449073bbd0a/alertmanager/api/v2/silences HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 312
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

[
    {
        "id": "d29d9df3-9125-4441-912c-70b05f86f973",
        "status": {
            "state": "active"
        },
        "updatedAt": "2021-10-22T19:32:11.763Z",
        "comment": "hello-world",
        "createdBy": "test-person",
        "endsAt": "2023-07-24T01:05:36.000Z",
        "matchers": [
            {
                "isEqual": true,
                "isRegex": true,
                "name": "job",
                "value": "hello"
            }
        ],
        "startsAt": "2021-10-22T19:32:11.763Z"
    }
]

ListRules

The ListRules retrieves information about the rules configured in the workspace.

Valid HTTP verbs:

GET

Valid URIs:

/workspaces/workspaceId/api/v1/rules

Sample request

GET /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/rules HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 423
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
    "status": "success",
    "data": {
        "groups": [
            {
                "name": "test-1.rules",
                "file": "test-rules",
                "rules": [
                    {
                        "name": "record:1",
                        "query": "sum(rate(node_cpu_seconds_total[10m:1m]))",
                        "labels": {},
                        "health": "ok",
                        "lastError": "",
                        "type": "recording",
                        "lastEvaluation": "2021-10-21T21:22:34.429565909Z",
                        "evaluationTime": 0.001005399
                    }
                ],
                "interval": 60,
                "lastEvaluation": "2021-10-21T21:22:34.429563992Z",
                "evaluationTime": 0.001010504
            }
        ]
    },
    "errorType": "",
    "error": ""
}

PutAlertManagerSilences

The PutAlertManagerSilences operation creates a new alert silence or updates an existing one.

Valid HTTP verbs:

POST

Valid URIs:

/workspaces/workspaceId/alertmanager/api/v2/silences

URL query parameters:

silence An object that represents the silence. The following is an example:

{
  "id": "string",
  "matchers": [
    {
      "name": "string",
      "value": "string",
      "isRegex": true,
      "isEqual": true
    }
  ],
  "startsAt": "2021-09-23T17:01:53.269Z",
  "endsAt": "2021-09-24T17:01:53.269Z",
  "createdBy": "string",
  "comment": "string"
}

Sample request

POST /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/alertmanager/api/v2/silences HTTP/1.1
Content-Length: 281, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

{
   "matchers":[
      {
         "name":"job",
         "value":"hello",
         "isRegex":false,
         "isRegex":true
      }
   ],
   "startsAt":"2020-07-23T01:05:36+00:00",
   "endsAt":"2023-07-24T01:05:36+00:00",
   "createdBy":"test-person",
   "comment":"hello-world"
}

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 53
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin

{
    "silenceID": "512860da-74f3-43c9-8833-cec026542b32"
}

QueryMetrics

The QueryMetrics operation evaluates an instant query at a single point in time or over a range of time.

Valid HTTP verbs:

GET, POST

Valid URIs:

/workspaces/workspaceId/api/v1/query This URI evaluates an instant query at a single point in time.

/workspaces/workspaceId/api/v1/query_range This URI evaluates an instant query over a range of time.

URL query parameters:

query=<string> A Prometheus expression query string. Used in both query and query_range.

time=<rfc3339 | unix_timestamp> (Optional) Evaluation timestamp if you are using the query for an instant query at a single point in time.

timeout=<duration> (Optional) Evaluation timeout. Defaults to and is capped by the value of the -query.timeout flag. Used in both query and query_range.

start=<rfc3339 | unix_timestamp> Start timestamp if you are using query_range to query for a range of time.

end=<rfc3339 | unix_timestamp> End timestamp if you are using query_range to query for a range of time.

step=<duration | float> Query resolution step width in duration format or as a float number of seconds. Use only if you are using query_range to query for a range of time, and required for such queries.

Duration

A duration in a Prometheus-compatible API is a number, followed immediately by one of the following units:

  • ms milliseconds

  • s seconds

  • m minutes

  • h hours

  • d days, assuming a day always has 24h

  • w weeks, assuming a week always has 7d

  • y years, assuming a year always has 365d

Sample request

POST /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/query?query=sum(node_cpu_seconds_total) HTTP/1.1
Content-Length: 0, 
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Grafana/8.1.0

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length: 132
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
content-encoding: gzip

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [
            {
                "metric": {},
                "value": [
                    1634937046.322,
                    "252590622.81000024"
                ]
            }
        ]
    }
}

RemoteWrite

The RemoteWrite operation writes metrics from a Prometheus server to a remote URL in a standardized format. Typically, you will use an existing client such as a Prometheus server to call this operation.

Valid HTTP verbs:

POST

Valid URIs:

/workspaces/workspaceId/api/v1/remote_write

URL query parameters:

None

RemoteWrite has an ingestion rate of 70,000 samples per second and ingestion burst size of 1,000,000 samples.

Sample request

POST /workspaces/ws-b226cc2a-a446-46a9-933a-ac50479a5568/api/v1/remote_write --data-binary "@real-dataset.sz" HTTP/1.1
Authorization: AUTHPARAMS
X-Amz-Date: 20201201T193725Z
User-Agent: Prometheus/2.20.1
Content-Type: application/x-protobuf
Content-Encoding: snappy
X-Prometheus-Remote-Write-Version: 0.1.0

body
Note

For the request body syntax, see to the protocol buffer definition at https://github.com/prometheus/prometheus/blob/1c624c58ca934f618be737b4995e22051f5724c1/prompb/remote.pb.go#L64.

Sample response

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Length:0
Connection: keep-alive
Date: Tue, 01 Dec 2020 19:37:25 GMT
Content-Type: application/json
Server: amazon
vary: Origin