Provisioning API – Deployments


Overview

The SearchStax Managed Search service provides an API supporting the creation, deletion and management of Solr deployments.

Platinum and Platinum Plus Clients Only!

The SearchStax API suite is available to our Platinum and Platinum Plus clients only, as noted on our Pricing page.

This page describes how to create and manage deployments using API methods.

The API can be accessed through any tool that assembles HTTP requests and dispatches them to a server. Among these would be the Python coreapi package, the Postman tool, and cURL. For Windows, use PowerShell 7+.

Account Owner, Admin, or Technical Contact

To run the SearchStax Provisioning API, you must be the account Owner, an account Admin, or a Technical Contact. See SearchStax User Roles.

Symbols enclosed in carets (< and >) such as <username> are metavariables. Substitute your local values when you encounter them in the examples.

Contents:

Related Pages:

Deployment

account > deployment > create

This method lets you create a new deployment. Note that a successful response indicates only that deployment creation was authorized and has begun. It can take up to an hour to bring a new deployment on line depending on the cloud provider.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/

where <account_name> is the name of the tenant account.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "name": "SolrFromAPI",
    "application": "Solr",
    "application_version": "7.3.1",
    "termination_lock": false,
    "plan_type": "DedicatedDeployment",
    "plan": "NDN1-AWS-S",
    "region_id": "ap-northeast-1",
    "cloud_provider_id": "aws",
    "num_additional_app_nodes": 0
    "private_vpc": 2
}
ParameterDescriptionExample
name
required
string
The name of the new deployment“SolrFromAPI”
application
required
string
The application for which this deployment is being created.“Solr”
application_version
required
string
The version of application being deployed. Detailed information regarding application versions is available from the List Plans method.“7.3.1”
termination_lock
required
boolean
Whether or not the deployment should be shielded from API deletion.false
plan_type
required
string
Available plan type could be SharedDeployment or DedicatedDeployment. Currently SearchStax only supports DedicatedDeployment (the default).“DedicatedDeployment”
plan
required
string
The plan of the selected plan type. Detailed information regarding plans available can be fetched using List Plans method.“NDN1-AWS-S”
region_id
required
string
The region ID of the region where deployment has to be created. Detailed information regarding regions available can be fetched using List Plans method.“ap-northeast-1”
cloud_provider_id
required
string
The cloud provider to be used to create this deployment. Detailed information regarding cloud providers available can be fetched using List Plans method.“aws” “azure” “gcp”
num_additional_app_nodes
optional
number
The number of additional nodes to be added to the deployment beyond the default number of nodes.

If the deployment will grow to a large number of nodes, create it with 10 “additional” nodes. This allocates a large IP subnet that can scale up gracefully. You may then use the SearchStax Dashboard to manage the actual number of nodes up or down as needed.
“10”
private_vpc
optional
number
The ID of the Private VPC where the new deployment will appear. Private VPC IDs are available from the account > privatevpc > list method.“2”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Token <token>" \
  --data "{
    \"name\": \"SolrFromAPI\",
    \"application\": \"Solr\",
    \"application_version\": \"7.3.1\",
    \"termination_lock\": false,
    \"plan_type\": \"DedicatedDeployment\",
    \"plan\": \"NDN1-AWS-S\",
    \"region_id\": \"ap-northeast-1\",
    \"cloud_provider_id\": \"aws\",
    \"num_additional_app_nodes\": \"0\"
    \"private_vpc\": \"2\"
    }"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$body = @{
    name='SolrFromAPI'
    application='Solr'
    application_version='7.5.0'
    termination_lock='false'
    plan_type='DedicatedDeployment'
    plan='NDN1-AWS-S'
    region_id='us-west-1'
    cloud_provider_id='aws'
    num_additional_app_nodes='0'
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -Body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing …

{
  "name": "SolrFromAPI",
  "uid": "ss123456",
  "application": "Solr",
  "application_version": "7.5.0",
  "tier": "Silver",
  "http_endpoint": null,
  "status": "Pending",
  "provision_state": "Pending",
  "termination_lock": false,
  "plan_type": "DedicatedDeployment",
  "plan": "NDN1-AWS-S",
  "is_master_slave": false,
  "vpc_type": "Public",
  "vpc_name": "",
  "region_id": "us-west-1",
  "cloud_provider": "Amazon Web Services"
  "cloud_provider_id": "aws",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Node",
  "num_nodes_default": 1,
  "num_zookeeper_nodes_default": 0,
  "num_additional_zookeeper_nodes": 0,
  "servers": [],
  "zookeeper_ensemble": null,
  "tag": [],
  "specifications": {
    "jvm_heap_memory": "536870912",
    "disk_space": "8589934592",
    "physical_memory": "1073741824"
  },
  "backups_enabled": false,
  "dr_enabled": false,
  "sla_active": false,
  "state_changed": null,
  "term_end": null,
  "date_created": "2023-01-25",
  "application_nodes_count": 1,
  "selected_node_count": 0,
  "savings": {
    "one_year_saving_perc": "52.38",
    "three_year_saving_perc": "59.52"
  },
  "dr_plan_type": null,
  "subscription": "monthly",
  "security_pack": false,
  "desired_tier": "silver",
  "backup": null,
  "onboarding": false,
  "selected_plan_memory": 0.0,
  "selected_plan_storage": 0.0,
  "dr": null,
  "payment_method": null,
  "purchase_order": null
}

Note that the servers and the zookeeper_ensemble values are not initially available because those entities take time to create. Wait until the deployment is up and running, and then use the account > deployment > list method (below).

account > deployment > delete

This method deletes a deployment from the tenant account. Note that a successful response means only that the deletion process was authorized and has begun. It can take up to an hour to delete a deployment depending on the cloud provider.

DELETE https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$RESULT = Invoke-RestMethod -Method Delete -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/" 
$RESULT = $RESULT | ConvertTo-Json

A success response will identify the deleted deployment.

{
  "success": "true",
  "message": "Successfully deleted ss123456"
}

Invalid UID will throw a Not Found error.

{
  "detail": "Not found."
}

Subject to Termination Lock

The Termination Lock button on the Deployment Details page in the SearchStax Dashboard protects the deployment from API deletion until the lock is released.

If the Termination Lock is set, you’ll see a message like this one:

{
   "detail":"This deployment has Termination Lock enabled. Please first remove the termination lock, and then retry deleting the deployment."
}

account > deployment > list

This method lists the deployments of an account along with their deployment details.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/?page=<n>&page_size=<m>

where <account_name> is the name of the tenant account; page (optional) is the page number of a multi-page list; and page_size (optional) is the number of deployments to include on a page.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$DEPLOYMENTS = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/" 
$DEPLOYMENTS = $DEPLOYMENTS | ConvertTo-Json

A successful response contains a JSON object containing a list of deployment descriptions. Note that next and previous are literal URLs that fetch the next and previous pages of a multi-page list of deployments.

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "ListByAPI",
      "uid": "ss123456",
      "application": "Solr",
      "application_version": "8.11.2",
      "tier": "Gold",
      "http_endpoint": "https://ss123456-7hp6b4y0-us-west-1-aws.searchstax.com/solr/",
      "status": "Configuring Deployment",
      "provision_state": "Pending",
      "termination_lock": false,
      "plan_type": "DedicatedDeployment",
      "plan": "NDC128-AWS-G",
      "is_master_slave": false,
      "vpc_type": "Public",
      "vpc_name": "",
      "region_id": "us-west-1",
      "cloud_provider": "Amazon Web Services",
      "cloud_provider_id": "aws",
      "num_additional_app_nodes": 0,
      "deployment_type": "Dedicated Cluster",
      "num_nodes_default": 2,
      "num_zookeeper_nodes_default": 3,
      "num_additional_zookeeper_nodes": 0,
      "servers": "ss123456-5 ss123456-4 ss123456-3 ss123456-2 ss123456-1",
      "zookeeper_ensemble": "ss123456-7hp6b4y0-1-us-west-1-aws.searchstax.com:2181,ss123456-7hp6b4y0-2-us-west-1-aws.
rchstax.com:2181,ss123456-7hp6b4y0-3-us-west-1-aws.searchstax.com:2181",
      "tag": "",
      "specifications": "@{disk_space=; physical_memory=; jvm_heap_memory=}",
      "backups_enabled": false,
      "dr_enabled": false,
      "sla_active": false,
      "state_changed": null,
      "term_end": null,
      "date_created": "2023-01-25",
      "application_nodes_count": 2,
      "selected_node_count": 0,
      "savings": "@{one_year_saving_perc=0.00; three_year_saving_perc=15.00}",
      "dr_plan_type": null,
      "subscription": "yearly",
      "security_pack": false,
      "desired_tier": "gold",
      "backup": null,
      "onboarding": false,
      "selected_plan_memory": 0.0,
      "selected_plan_storage": 0.0,
      "dr": null,
      "payment_method": null,
      "purchase_order": null
    }, <plus more deployments, if any...>

account > deployment > read

This method lists the properties of a specific deployment.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$DETAILS = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/" 
$DETAILS1 = $DETAILS | ConvertTo-Json

The response is a JSON document containing the detailed properties of a deployment:

{
  "name": "ReadByAPI",
  "uid": "ss123456",
  "application": "Solr",
  "application_version": "7.7.2",
  "tier": "Silver",
  "http_endpoint": "https://ss123456-hjmll0ug-us-west-1-aws.searchstax.com/solr/",
  "status": "Running",
  "provision_state": "Done",
  "termination_lock": true,
  "plan_type": "DedicatedDeployment",
  "plan": "NDN1",
  "is_master_slave": false,
  "vpc_type": "Public",
  "vpc_name": "",
  "region_id": "us-west-1",
  "cloud_provider": "Amazon Web Services",
  "cloud_provider_id": "aws",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Node",
  "num_nodes_default": 1,
  "num_zookeeper_nodes_default": 0,
  "num_additional_zookeeper_nodes": 0,
  "servers": [
    "ss123456-1"
  ],
  "zookeeper_ensemble": "ss123456-hjmll0ug-1-us-west-1-aws.searchstax.com:2181",
  "tag": [
    "DoNotDelete"
  ],
  "specifications": {
    "jvm_heap_memory": "536870912",
    "disk_space": "8589934592",
    "physical_memory": "1073741824"
  },
  "backups_enabled": false,
  "dr_enabled": false,
  "sla_active": false,
  "state_changed": "1571931445",
  "term_end": null,
  "date_created": "2019-10-24",
  "application_nodes_count": 1,
  "selected_node_count": 0,
  "savings": {
    "one_year_saving_perc": "52.50",
    "three_year_saving_perc": "64.38"
  },
  "dr_plan_type": null,
  "subscription": "monthly",
  "security_pack": false,
  "desired_tier": null,
  "backup": null,
  "onboarding": false,
  "selected_plan_memory": 0.0,
  "selected_plan_storage": 0.0,
  "dr": null,
  "payment_method": null,
  "purchase_order": null
}

Converting specifications to GB

In a PowerShell script, we can convert the reported specification values to GB using the following lines. Do not convert the output to JSON before making these calculations:


$GB = [math]::pow( 1024, 3 )  # To convert raw memory to rounded GB like the UI uses.

$DISK = $DETAILS.specifications.disk_space / $GB
$JVM = $DETAILS.specifications.jvm_heap_memory / $GB
$MEMORY = $DETAILS.specifications.physical_memory / $GB


Write-Host "Disk space is $DISK GB"
Write-Host "JVM heap memory is $JVM GB"
Write-Host "Physical memory is $MEMORY GB"

account > deployment > get_deployment_health

This method gets the deployment’s health using its UID.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/deployment-health/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/deployment-health/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/deployment-health/" 
$RESULT = $RESULT | ConvertTo-Json

Responses are JSON documents like those shown below. These examples are from a three-node cluster:

  • All nodes are running.
{ "status": "OK", "level": "success" }

  • One or two of the three servers is down.
{ "status": "Warn", "level": "warning" }

  • All three servers are down.
{ "status": "Error", "level": "danger" }

  • Invalid UID throws a Not Found error.
{ "detail": "Not found." }


account > deployment > collections_health

This method gets the health of a deployment’s collections.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/collection-health/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/collections-health/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/collections-health/" 
$RESULT = $RESULT | ConvertTo-Json

Responses are JSON documents like those shown below.

  • All collections are running.
{ "success": true, "healthy": true}

  • One or more collections are degraded.
{ "success": true, "healthy": false }

  • API endpoint failure.
{ "success": false, "error": "some message" }

account > deployment > rolling_restart

This method lets you restart the Solr or Zookeeper nodes of a cluster in a rolling manner.

PUT https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/rolling-restart/

where <account_name> is the name of the tenant account and <uid> is the ID number of the deployment.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "solr": true,
    "zookeeper": false
}
ParameterDescriptionExample
solr
required boolean
If true, will restart the Solr nodes. Default is true. true
zookeeper
required boolean
If true, will restart the Zookeeper nodes. Default is false.false

When invoked from Linux (Bash script):

curl --request PUT "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/rolling-restart/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Token <token>" \
  --data "{
    \"solr\": true,
    \"zookeeper\": false
    }"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    solr='true'
    zookeeper='false'
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Put -Body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/rolling-restart/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing …

{
  "detail": "Rolling restart initiated"
}

If the message says, “The specified deployment is not ready for a rolling restart,” it means that a rolling restart is already underway, or that one of the nodes is down.

account > deployment > server > start_solr

This method starts an individual Solr node using its UID.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/start-solr/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <node> is the ID of the specific node.

This method uses either Token authentication or API Key authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/start-solr/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$NODE = "ss123456-4"

$RESULT = Invoke-RestMethod -Method Post -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/$NODE/start-solr/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

{
  "success": true
}

account > deployment > server > stop_solr

This method stops an individual Solr node using its UID.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/stop-solr/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <node> is the ID of the specific node.

This method uses either Token authentication or API Key authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/stop-solr/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$NODE = "ss123456-4"

$RESULT = Invoke-RestMethod -Method Post -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/$NODE/stop-solr/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

{
  "success": true
}

account > deployment > server > host_status

This method returns the status of an individual Solr node using its UID.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/host-status/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <node> is the number of the specific node.

This method uses either Token authentication or API Key authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/host-status/" \
  --header "Authorization: Token <token>

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$NODE = "4"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/$NODE/host-status/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

{
  "level": "success",
  "status": "OK"
}

account > deployment > server > list

This method returns a list of nodes making up a Solr deployment.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses either Token authentication or API Key authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

[
  {
    "sn": 1,
    "node": "ss123456-1",
    "private_address": "10.0.1.78",
    "dns_address": "ss123456-jkzg2pr0-1-ca-central-1-aws.searchstax.com",
    "status": "Running",
    "solr": false,
    "zookeeper": true,
    "silk": false
  },
  {
    "sn": 2,
    "node": "ss123456-2",
    "private_address": "10.0.1.74",
    "dns_address": "ss123456-jkzg2pr0-2-ca-central-1-aws.searchstax.com",
    "status": "Running",
    "solr": false,
    "zookeeper": true,
    "silk": false
  },
]

account > plan > list

This method lists the available deployment plans and the regions where those plans are available.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/plan/?page=1&application=Solr&plan_type=DedicatedPlan

where <account_name> is the name of the tenant account. There are three query parameters: page is the page number within the paginated result set; application requests plans for either “Solr” or “elasticsearch”; and plan_type is “DedicatedPlan”. (The API currently supports only one plan type.)

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/plan/?page=1&application=Solr&plan_type=DedicatedPlan" \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/plan/?page=1&application=Solr&plan_type=DedicatedPlan" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document with the following values –

ParameterDescriptionExample
name
string
The name of the plan“NDN4-AWS-S”
description
string
The description of the plan.“Dedicated Node – 4GB/32GB”
application
object
JSON object with details of application selected{
“name”: “Solr”,
“description”: “Apache Solr”,
“tag”: “solr”
}
application_versions
list of strings
List of available application versions[
“8.11.2”,
“8.11.1”,
“8.8.2”,
“8.8.1”,
“8.6.3”,
and many more…
]
plan_type
string
The plan type selected“DedicatedPlan”
plan_regions
list of objects
List of JSON objects containing information associated with each region.{
“price”: 160,
“additional_application_node_price”: 0,
“additional_zookeeper_node_price”: 0,
“region_id”: “ap-northeast-1”,
“cloud_provider”: “Amazon Web Services”,
“cloud_provider_id”: “aws”
}
trial_available
boolean
Whether the plan is available in trial accountfalse

account > usage > list

This method produces a list of the billable usage events of dedicated deployments in an account during a specific year and month.

GET /api/rest/v2/account/<account_name>/usage/<year>/<month>/

where <account_name> is the name of the tenant account, <year> is an integer (2023), and <month> is an integer (1-12).

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/usage/<year>/<month>/ \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$YEAR = "2023"
$MONTH = "3"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/usage/$YEAR/$MONTH/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document containing a list of usage events like this one:

  {
    "startDate": "2022-04-01",
    "endDate": "2022-04-30",
    "objectID": "ss123456",
    "SKU": "NDN4-AWS-S",
    "currency": "USD",
    "amount": "192.00",
    "usage": 30,
    "tagCollection": []
  },

Usage is the number of billable days between startDate and endDate, inclusively. In the case of backup storage, it is the number of bytes stored.

account > usage-extended > list

This method produces a list of billable usage events for serverless indexes of an account during a specific year and month.

GET /api/rest/v2/account/<account_name>/usage-extended/<year>/<month>/

where <account_name> is the name of the tenant account, <year> is an integer (2023), and <month> is an integer (1-12).

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/usage-extended/<year>/<month>/ \
  --header "Authorization: Token <token>" 

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$YEAR = "2023"
$MONTH = "3"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/usage-extended/$YEAR/$MONTH/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document containing a list of usage events like this one:

  {
    "startDate": "2023-12-01",
    "endDate": "2023-12-31",
    "objectID": "4008_QuickStart",
    "SKU": "SH-STARTER",
    "usage": 31,
    "tagCollection": [
      "Serverless_Index",
      "type:index"
    ],
    "currency": "USD",
    "amount": 9.15,
    "extendedAttributes": [
      "createdDate:2023-10-06",
      "totalRequests:0",
      "indexID:4008",
      "name:QuickStart",
      "region:us-west-2",
      "indexSize:0.002734375",
      "indexSizeWUnit:2.8 KB",
      "status:active",
      "orderStatus:completed",
      "subscription:yearly"
    ]
  }

Usage is the number of billable days between startDate and endDate, inclusively. In the case of backup storage, it is the number of bytes stored. The list of extendedAttributes describes a single serverless index (collection).

Questions?

Do not hesitate to contact the SearchStax Support Desk.