# Get API usage statistics

# Overview

Gets the API usage statistics for an organisation for the current calendar month. Usage statistics are available for previous months by using the year and month query fields.

A part of the usage statistics are not calculated in real time. The response will specify in the lastUpdated field the latest date considered in calculating the usage. The delay you should see is around 15 minutes.

The important metrics that are calculated are the number of images processed, the number of Vision API requests and the relevant credit usage.

# Vision API credits

The number of monthly available credits is given by the limit type: fixed or unlimited.

When the limit is fixed the response will specify the total number of credits available, used, remaining. The pricing is fixed per month and specified in your package. Making more requests than included in your package could generate a 402 Payment Required response. Remaining credits at the end of the month don't report over to the next month.

When the limit is unlimited a number of credits will be included in your monthly package and the credits above that number will be charged separately in your monthly invoice. To move over to an unlimited package, please contact billing.

Each type of Vision API request has an associated number of credits. The formula used is: credits of type 'A' = "number of type 'A' requests" x "multiplier for type 'A'". The mapping is shown in the requestCredits field. The total number of credits is calculated adding the credits for all types of requests.

Only requests to the Vision API are charged, those to Admin API only incur fees when images are processed and those to Analytics API are free as the information provided by you is used to enhance your results.

We only count successful Vision API requests, even if the number of results is zero (narrow filters).

# Process images

The number of yearly available images to be processed is given by the limit type: fixed or unlimited.

When the limit is fixed the response will specify the total, remaining and processed number of images. The pricing is fixed per year and specified in your package. We may postpone processing more images than included in your package. Remaining usage at the end of the year doesn't report over to the next year. If you would like to upgrade your package please contact billing.

When the limit is unlimited a number of process images will be included in your monthly package and the usage above that number will be charged separately in your invoice.

We consider an image is processed every time we get information about a new image URL: initially when you push content, when the URL for an image changes or when you request for the URL to be re-processed when its source changed (by appending a querystring parameter).

When adding content to a dataset, each item is uniquely identified by its ID. So two items with different IDs can have the same URL. Considering the data behind an image URL can change without affecting the URL we don't check if that image URL has been processed before nor reuse the information we extracted from it previously. Therefore the same URL will be processed twice and it will be considered twice when calculating the usage.

We only count successfully processed images. Please review the documentation on adding content to a dataset.

# Input

Endpoint

GET /orgs/:organisation/usage

Field	Type	Required	Value Description
organisation	String	yes	The organisation name
year	Number	no	The year for the usage statistics
month	Number	no	The month for the usage statistics

# Request

curl -X GET \
     -H "Authorization: token my-org-api-token" \
     -H "Accept: application/vnd.visii.v2+json" \
     "https://api.visii.com/orgs/my-org/usage?year=2019&month=1"

# Response

Field	Type	Value Description
status	String	The status of the response
credits	Object	The credits details
credits.limitType	String	The API requests limit type: `fixed` or `unlimited`
credits.limit	Number	The monthly credits limit value if `limitType = fixed`, optional
credits.remaining	Number	The number of remaining credits for the requested month if `limitType = fixed`, optional
credits.used	Number	The number of used credits for the requested month
credits.month	Number	The month of the requested usage
credits.year	Number	The year of the requested usage
images	Object	The image usage details
images.limitType	String	The images limit type: `fixed` or `unlimited`
images.limit	Number	The yearly images limit value if `limitType = fixed`, optional
images.processed	Number	The number of processed images for the requested year
images.remaining	Number	The number of remaining processing image requests for the requested year if `limitType = fixed`
images.total	Number	The number of images in use across all datasets
images.year	Number	The year of the requested usage
datasets	Object	The usage details per dataset
datasets[name].images	Number	The number of active images in the dataset
datasets[name].usage	Object	Usage statistics for the current dataset
datasets[name].usage.type	String	The type of request (e.g. `explore`, `lens`, `similar`)
datasets[name].usage.requests	Number	The number of `type` requests
datasets[name].usage.credits	Number	The number of credits for the `type` of requests
datasets[name].deleted	Boolean	True if the dataset has been deleted, optional
lastUpdated	String	The latest date considered in the calculation of these usage statistics
requestCredits	Object	The mapping between type of requests and number of credits
requestCredits[request-type]	Number	The number of credits used when making a `request-type` request

HTTP/1.1 200 OK
{
  "status": "ok",
  "usage": {
    "credits": {
      "limit": 10000,
      "limitType": "fixed",
      "month": 11,
      "remaining": 2000,
      "used": 8000,
      "year": 2018
    },
    "datasets": {
      "bongos": {
        "images": 777,
        "usage": [
          { "credits": 4000, "requests": 4000, "type": "explore" },
          { "credits": 3000, "requests": 1000, "type": "lens" },
          { "credits":    0, "requests": 1000, "type": "track" }
        ]
      },
      "bongos2": {
        "images": 888,
        "usage": [
          { "credits": 1000, "requests": 1000, "type": "explore" },
          { "credits":    0, "requests": 2345, "type": "track" }
        ]
      },
      "bongos3": {
        "images": 500,
        "usage": [
          { "credits": 100, "requests": 100, "type": "explore" }
        ],
        "deleted": true
      }
    },
    "images": {
      "limit": 10000,
      "limitType": "fixed",
      "processed": 2000,
      "remaining": 8000,
      "total": 1665,
      "year": 2018
    },
    "lastUpdated": "2019-01-13T12:34:56Z",
    "requestCredits": {
      "assistant": 2,
      "explore": 1,
      "lens": 3,
      "similar": 0.5,
      "track": 0
    }
  }
}

← Enable indexing of metadata arrays