Experiment with this API

Report Usage

Use this endpoint to report the usages of a set of assets. The count of assets submitted in a single batch to this endpoint is limited to 1000. Note that all asset Ids specified must be valid or the operation will fail causing no usages to be recorded. In this case, you will need to remove the invalid asset Ids from the query request and re-submit the query.

Quickstart

You'll need an API key and a Resource Owner Grant access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key.

Use the following endpoint to submit usages:

PUT https://api.gettyimages.com/v3/usage-batches/<batchid>

Add your API key and the Resource Owner Grant access token to the request header:

Api-Key: <your api key>
Authorization: Bearer <your secure access token>

Your request would look like this using cUrl:

curl -X PUT -H "Authorization: Bearer <access token>" -H "Api-Key: <your api key>" -H "Content-Type: application/json" -d '{
  "asset_usages": [
    {
      "asset_id": "<asset id>",
      "quantity": <usage quantity>,
      "usage_date": "<date of use>"
    }
  ]
}' 'https://api.gettyimages.com/v3/usage-batches/<unique batch id>'

Note that date of use can be in any unambiguous date format.

The response body for a success response of 201 will look like the following example:

{
  "total_asset_usages_processed": <usage quantity>
}

An error response body for a code of 400 will look like the following example:

{
  "ErrorCode": "Invalid Request",
  "ErrorMessage": "Error in the application."
}

Request Headers

Api-Key string Api-Key Required.
Accept-Language string Accept-Language parameter optional. Used to restrict the set of natural languages that are preferred as a response to the request.
Authorization string Authorization token required. Used for applying content access restrictions. Use one of the OAuth2 grants to auto-populate this value. Required.

URI Path Parameters

id string Specifies a unique batch transaction id to identify the report. Required.

Request Body Fields

report_usage_batch_request

asset_usages array [asset_usage ] Identifies the list of asset id, usage count and date of usage combinations to record.

asset_usage

asset_id string Specifies the Id of the asset that was used.
quantity integer Specifies the number of times the asset was used.
usage_date string Identifies the date the asset was used, in ISO 8601 format (e.g., YYYY-MM-DD), time is not needed.

Response Body Fields

report_usage_batch_response

invalid_assets array [ string ] Identifies a list of asset ids submitted that did not match known Getty asset ids.
total_asset_usages_processed integer Specifies the number of asset usage records that were successfully recorded.

Response Status Codes

200 Success - All usages reported were successfully recorded.
400 InvalidRequest - The content of the request was invalid. Most commonly this is due to either too many assets specified, no assets or invalid JSON.
400 InvalidAssets - Invalid assets found in the request.
401 AuthorizationTokenRequired - Authorization token was missing or not valid.
401 UnauthorizedToReportUsage - User was not authorized to report usages. Contact your Getty Images Account Manager to discuss options for submitting your usage data.
409 TransactionIdDuplicated - The id parameter supplied was already used in a previous usage report.