Instance Actions
https://api.losant.com/instances/INSTANCE_ID
Below are the various requests that can be performed against the Instance resource, as well as the expected parameters and the potential responses.
Generate Report
Generates a CSV report on instance stats
Method And Url
POST https://api.losant.com/instances/INSTANCE_ID
/generateReport
Authentication
A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Instance, all.Instance.read, all.User, all.User.read, instance.*, or instance.generateReport.
Request Path Components
Path Component | Description | Example |
---|---|---|
INSTANCE_ID | ID associated with the instance | 575ec8687ae143cd83dc4a97 |
Request Headers
Name | Required | Description | Default |
---|---|---|---|
Authorization | Y | The token for authenticating the request, prepended with Bearer |
Request Body
The body of the request should be serialized JSON that validates against the Instance Report Options Post schema. For example, the following would be a valid body for this request:
{
"email": "email@example.com",
"callbackUrl": "https://example.com/callback",
"resourceGroupBy": "organization",
"dateGroupBy": "month",
"includeSandbox": false,
"start": "2020-01-01T00:00:00.000Z",
"end": "2020-01-31T11:59:59.999Z"
}
Curl Example
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
-X POST \
https://api.losant.com/instances/INSTANCE_ID/generateReport
Successful Responses
Code | Type | Description |
---|---|---|
202 | Job Enqueued API Result | If generation of report was successfully started |
Error Responses
Code | Type | Description |
---|---|---|
400 | Error | Error if malformed request |
Get
Returns an instance
Method And Url
GET https://api.losant.com/instances/INSTANCE_ID
Authentication
A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Instance, all.Instance.read, all.User, all.User.read, instance.*, or instance.get.
Request Path Components
Path Component | Description | Example |
---|---|---|
INSTANCE_ID | ID associated with the instance | 575ec8687ae143cd83dc4a97 |
Request Headers
Name | Required | Description | Default |
---|---|---|---|
Authorization | Y | The token for authenticating the request, prepended with Bearer |
Curl Example
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
-X GET \
https://api.losant.com/instances/INSTANCE_ID
Successful Responses
Code | Type | Description |
---|---|---|
200 | Instance | A single instance |
Error Responses
Code | Type | Description |
---|---|---|
400 | Error | Error if malformed request |
404 | Error | Error if instance was not found |
Historical Summaries
Return historical summary entries for an instance
Method And Url
GET https://api.losant.com/instances/INSTANCE_ID
/historicalSummaries
Authentication
A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Instance, all.Instance.read, all.User, all.User.read, instance.*, or instance.historicalSummaries.
Request Path Components
Path Component | Description | Example |
---|---|---|
INSTANCE_ID | ID associated with the instance | 575ec8687ae143cd83dc4a97 |
Request Query Parameters
Name | Required | Description | Default | Example |
---|---|---|---|---|
month | N | Timestamp within the month to report a summary for. | now | month=1609459204518 |
sortField | N | Field to sort the results by. Accepted values are: resourceId, currentPeriodStart | currentPeriodStart | sortField=resourceId |
sortDirection | N | Direction to sort the results in. Accepted values are: asc, desc | asc | sortDirection=asc |
page | N | Which page of results to return | 0 | page=0 |
perPage | N | How many items to return per page | 100 | perPage=10 |
filterField | N | Field to filter the results by. Blank or not provided means no filtering. Accepted values are: resourceType, resourceId, ownerId, ownerType | filterField=resourceType | |
filter | N | Filter to apply against the filtered field. Blank or not provided means no filtering. | filter=organization |
Request Headers
Name | Required | Description | Default |
---|---|---|---|
Authorization | Y | The token for authenticating the request, prepended with Bearer |
Curl Example
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
-X GET \
https://api.losant.com/instances/INSTANCE_ID/historicalSummaries
Successful Responses
Code | Type | Description |
---|---|---|
200 | Historical Summaries | Collection of historical summaries |
Error Responses
Code | Type | Description |
---|---|---|
400 | Error | Error if malformed request |
Patch
Updates information about an instance
Method And Url
PATCH https://api.losant.com/instances/INSTANCE_ID
Authentication
A valid api access token is required to access this endpoint. The token must include at least one of the following scopes: all.Instance, all.User, instance.*, or instance.patch.
Request Path Components
Path Component | Description | Example |
---|---|---|
INSTANCE_ID | ID associated with the instance | 575ec8687ae143cd83dc4a97 |
Request Headers
Name | Required | Description | Default |
---|---|---|---|
Authorization | Y | The token for authenticating the request, prepended with Bearer |
Request Body
The body of the request should be serialized JSON that validates against the Instance Patch schema. For example, the following would be a valid body for this request:
{
"reportConfigs": [
{
"emails": [
"email@example.com"
],
"callbackUrl": "https://example.com/callback",
"resourceGroupBy": "organization",
"dateGroupBy": "month",
"includeSandbox": false,
"periods": 3,
"cron": "0 4 1 * *"
},
{
"emails": [
"email@example.com",
"anotheremail@example.com"
],
"resourceGroupBy": "application",
"dateGroupBy": "month",
"includeSandbox": true,
"cron": "0 4 1 * *"
}
]
}
Curl Example
curl -H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_API_ACCESS_TOKEN' \
-X PATCH \
-d '{"reportConfigs":[{"emails":["email@example.com"],"callbackUrl":"https://example.com/callback","resourceGroupBy":"organization","dateGroupBy":"month","includeSandbox":false,"periods":3,"cron":"0 4 1 * *"},{"emails":["email@example.com","anotheremail@example.com"],"resourceGroupBy":"application","dateGroupBy":"month","includeSandbox":true,"cron":"0 4 1 * *"}]}' \
https://api.losant.com/instances/INSTANCE_ID
Successful Responses
Code | Type | Description |
---|---|---|
200 | Instance | The updated instance object |
Error Responses
Code | Type | Description |
---|---|---|
400 | Error | Error if malformed request |
Was this page helpful?
Still looking for help? You can also search the Losant Forums or submit your question there.