Skip to content

Account Usage Data

Last updated: July 11, 2022


Subscription pricing and fee limits

ARD accounts incur usage based on your company's annual subscription. The subscription determines:

  • The total annual subscription fee limit. This is the maximum number of dollars the account can use to order imagery. Once this limit is reached, orders cannot be placed for the account.

  • The price of per square kilometer for each imagery age category.

The subscription can also set limits on the following, but these limits are not required:

  • The total number of square kilometers that can be ordered.

  • The number of square kilometers that can be ordered for each image age category.

  • Fee limits for individual users within the account.

When the ARD Support team creates your account, they set the following pricing data and fee limits:

Category Description
Limits The amount of imagery that can be purchased is limited by what is set in the ARD subscription agreement. Once an account reaches this limit, orders cannot be placed. The terms of the agreement may also set limits on imagery purchased in a specific age category.
Pricing Price per square kilometer. Pricing is set at the account level. The price is different for each imagery age category. The terms of the agreement may specify that imagery from one or more categories cannot be ordered.

Fee limits can also be set for individual users within the account. As an account administrator, you can set these limits when you create a user in your account or update the user record with these details. These can be set from the ARD Dashboard Account Users Page or by submitting a request to the Admin API. To learn how to set fee limits for a user in your account, see Account/User API reference.

Square kilometers (sqkm) limits may also be set for the account. This is an optional field that defaults to "unlimited".

Image age categories

ARD subscriptions include pricing for imagery based on its age. These categories are:

image age category time since acquisition
Fresh imagery less than or equal to 90 days
Standard imagery 91 days to 3 years
Training imagery more than 3 years

The subscription agreement will indicate a price for each category. It may also limit the amount of imagery that can be purchased in a specific category. We refer to this as a category fee limit. If no category fee limit is set, the total annual subscription fee limit applies.

View account usage limits

To see the pricing and fee limits set for your account, make a Get Account Details request to the ARD Admin/Account API resource. This will show details about the account you're a part of.

Example Account Details response:

{
    "account": {
        "account_id": "55237",
        "name": "My Account Name",
        "sap": "xxxx",
        "eval": false,
        "contract_start": "2022-01-01",
        "contract_end": "2023-01-01",
        "active": true,
        "created": "2022-01-01T12:42:23Z",
        "modified": "2022-02-11T12:42:23Z",
        "pricing": {
            "fresh_imagery_price": 30.0,
            "standard_imagery_price": 20.0,
            "training_imagery_price": 10.0
        },
        "limits": {
            "annual_subscription_fee_limit": 10000,
            "fresh_imagery_fee_limit": -1,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1,
            "sqkm_limit": null
        }
    },
    "links": {
        "self": "https://ard.maxar.com/api/v1/admin/account/55237",
        "users": "https://ard.maxar.com/api/v1/admin/account/55237/user",
        "applications": "https://ard.maxar.com/api/v1/admin/account/55237/application",
        "credentials": "https://ard.maxar.com/api/v1/admin/account/552376/credentials"
    },
    "response_timestamp": "2022-07-08T17:52:35Z"
}

View usage data

Usage data can be viewed from the ARD Dashboard or by making a request to the Usage API. The ARD Dashboard requires a date range before usage can be displayed. In the API, the date range is optional, but it may be needed if the amount of usage data is too large to return before the API request times out.

If the results of a usage data request are too large to be returned, you can make a request to the Asynchronous Usage endpoint. In this type of request, you'll specify an email address and a csv file will be sent to you when the request completes.

ARD Dashboard view

If you're an account administrator, you can view your account's usage data from the Maxar ARD Dashboard.

  1. Go to https://ard.maxar.com/dashboard

  2. Sign in with your ARD username and password. Your username is the email address where you received your account activation email.

  3. Go to the "Manage" tab and choose "Usage" from the dropdown menu.

  4. Enter a date range.

From this page, you can view your usage for the date range and the amount remaining. For more information, see Dashboard Help: Usage.

Usage API Request

You can request your account's usage data by making a request to the ARD Usage API. The request can be constrained by start_date and end_date query parameters. See ARD Usage API Reference for more information. Administrators and users can make this request.

Usage API Response

Example:

{
    "account_id": "55237",
        "usage": {
        "area": {
            "fresh_imagery_sqkm": 51.5,
            "standard_imagery_sqkm": 206.4,
            "training_imagery_sqkm": 9.3,
            "total_imagery_sqkm": 267.2,
            "estimate": false
        },
        "cost": {
            "fresh_imagery_cost": 52,
            "standard_imagery_cost": 1032,
            "training_imagery_cost": 27.9,
            "total_imagery_cost": 1111.9,
            "estimate": false
        },
        "limits": {
            "limit_sqkm": 3000000,
            "fresh_imagery_fee_limit": 500,
            "standard_imagery_fee_limit": -1,
            "training_imagery_fee_limit": -1,
            "annual_subscription_fee_limit": 100000
        },
        "available": {
            "available_sqkm": 2999732.8,
            "available_fresh_cost": 448,
            "available_standard_cost": -1,
            "available_training_cost": -1,
            "available_total_cost": 98888.1
        }
    },
    "usage_period": {
        "start_date": "2021-01-01",
        "end_date": "2022-01-01"
    },
    "links": {
        "account": "https://ard.maxar.com/api/v1/admin/account/55237"
    },
    "response_timestamp": "2021-07-28T20:12:24Z"
}
The value -1 for any field means unlimited. In most cases this means the field was not set. If a fee limit is set to -1, the available balance will be -1 since there is no fee limit to use for calculation.

The response to your request will show the following:

Usage type Description
area The square kilometers (sqkm) ordered by the account, to date. This section shows sqkm usage per image age category and the total used for the account.
cost The amount spent to date on imagery in the specified imagery age category. The total amount spent in all three categories is also displayed.
limits Displays the sqkm and fee limits set for the account.
available Shows the remaining available allotment for ordering ARD imagery, in dollars. The remaining sqkm allotment is also displayed in this section. See below to understand how available balances are calculated.

Asynchronous usage data request

If the results set for a usage request is too large to be returned before the request times out, you can make a request to the Asynchronous Usage endpoint.

This request requires an account ID and accepts start and end date parameters.

Asynchronous usage request example

POST usage/async/account/{account_id}

Example:

https://ard.maxar.com/api/v1/usage/async/account/55237?start_date=2022-04-23&end_date=2022-05-05

Include the following request body to have a csv usage file emailed to you:

{
  "notifications": [
        {
            "type": "email",
            "address": "example.email@mail.com"
        }
    ]
}

Asynchronous usage request response

{
    "id": "5963831769331387698",
    "account_id": "55237",
    "response_timestamp": "2022-07-12T17:29:08Z",
    "status": "RUNNING",
    "usage_period": {
        "start_date": "2021-01-01T00:00:00Z",
        "end_date": "2022-07-12T17:29:08Z"
    },
    "links": {
        "status": "https://ard.maxar.com/api/v1/usage/async/55237"
    }
}

To retrieve asynchronous usage results from the API, copy the "ID" from this response, and make a follow-up request to:

GET /usage/async/{request_id}

Example:

https://ard.maxar.com/api/v1/usage/async/5963831769331387698

This will return the same results as a standard Usage API request, shown above.

View usage estimates when selecting imagery

A request to the Select API returns an estimate of usage that would be incurred if the selected imagery is ordered.

Usage type Description
area The square kilometers covered by selected imagery. The "area" section displays the total sqkm usage and the sqkm usage by category.
cost The amount that will be spent on ordered imagery by imagery age category. The total amount spent in all three categories is also displayed.
limits Displays the sqkm and fee limits set for the account.
available Shows the remaining available allotment for ordering ARD imagery, in dollars. The remaining sqkm allotment is also displayed in this section. See below to understand how available balances are calculated.

Usage and cost estimates shown for the imagery selection may not match the usage costs incurred by order in some cases. For example:

  • Other users in the account may place orders and reduce the available allotment for the account.

  • One or more images in the selection could move from one image age category to another, reducing the cost of that image. For example, an image may be in the "fresh" image category when the selection is made, but it moved to the "standard" category by the time the order was placed.

View usage estimates for an order by submitting a "dry run" order request

The Ordering API allows a validation check before an order is placed. The validation check will return any errors that would prevent an order from being placed. The dry run response also estimates the usage that will be incurred when the order is placed.

To validate an order before placing it, add "dry_run":true to your order request. The response includes the estimated usage the order will consume when submitted.

Placing an ARD order

If an order request is submitted that will exceed the costs allowed by the subscription fee limits, it will return an error and the order will not be placed.

When an order successfully completes, an order status request will show the actual usage and cost of the order. Costs are not incurred until the ordered files are delivered to your cloud location. There is no charge for a failed order.

Documentation

Usage API Reference

Order API Reference

Back to top