Document Translation - Get Translations Status

Service:: Azure AI Services

API Version:: v1.0

Returns a list of batch requests submitted and the status for each request. This list only contains batch requests submitted by the user (based on the resource).

If the number of requests exceeds our paging limit, server-side paging is used. Paginated responses indicate a partial result and include a continuation token in the response. The absence of a continuation token means that no additional pages are available.

$top, $skip and $maxpagesize query parameters can be used to specify a number of results to return and an offset for the collection.

$top indicates the total number of records the user wants to be returned across all pages. $skip indicates the number of records to skip from the list of batches based on the sorting method specified. By default, we sort by descending start time. $maxpagesize is the maximum items returned in a page. If more items are requested via $top (or $top is not specified and there are more items to be returned), @nextLink will contain the link to the next page.

$orderBy query parameter can be used to sort the returned list (ex "$orderBy=createdDateTimeUtc asc" or "$orderBy=createdDateTimeUtc desc"). The default sorting is descending by createdDateTimeUtc. Some query parameters can be used to filter the returned list (ex: "status=Succeeded,Cancelled") will only return succeeded and cancelled operations. createdDateTimeUtcStart and createdDateTimeUtcEnd can be used combined or separately to specify a range of datetime to filter the returned list by. The supported filtering query parameters are (status, ids, createdDateTimeUtcStart, createdDateTimeUtcEnd).

The server honors the values specified by the client. However, clients must be prepared to handle responses that contain a different page size or contain a continuation token.

When both $top and $skip are included, the server should first apply $skip and then $top on the collection. Note: If the server can't honor $top and/or $skip, the server must return an error to the client informing about it instead of just ignoring the query options. This reduces the risk of the client making assumptions about the data returned.

GET {endpoint}/translator/text/batch/v1.0/batches

With optional parameters:

GET {endpoint}/translator/text/batch/v1.0/batches?$top={$top}&$skip={$skip}&$maxpagesize={$maxpagesize}&ids={ids}&statuses={statuses}&createdDateTimeUtcStart={createdDateTimeUtcStart}&createdDateTimeUtcEnd={createdDateTimeUtcEnd}&$orderBy={$orderBy}

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).
$maxpagesize	query		integer (int32) minimum: 1 maximum: 100	$maxpagesize is the maximum items returned in a page. If more items are requested via $top (or $top is not specified and there are more items to be returned), @nextLink will contain the link to the next page. Clients MAY request server-driven paging with a specific page size by specifying a $maxpagesize preference. The server SHOULD honor this preference if the specified page size is smaller than the server's default page size.
$orderBy	query		string[] maxLength: 1	the sorting query for the collection (ex: 'CreatedDateTimeUtc asc', 'CreatedDateTimeUtc desc')
$skip	query		integer (int32) minimum: 0 maximum: 2147483647	$skip indicates the number of records to skip from the list of records held by the server based on the sorting method specified. By default, we sort by descending start time. Clients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection. When both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection. Note: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options.
$top	query		integer (int32) minimum: 0 maximum: 2147483647	$top indicates the total number of records the user wants to be returned across all pages. Clients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection. When both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection. Note: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options.
createdDateTimeUtcEnd	query		string (date-time)	the end datetime to get items before
createdDateTimeUtcStart	query		string (date-time)	the start datetime to get items after
ids	query		string[] maxLength: 25	Ids to use in filtering
statuses	query		string[] maxLength: 5	Statuses to use in filtering

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string	Provide your cognitive services subscription key here.

Responses

Name	Type	Description
200 OK	TranslationsStatus	Successful request and returns the status of the all the operations Headers Retry-After: integer ETag: string
400 Bad Request	TranslationErrorResponse	Invalid request. Check input parameters
401 Unauthorized	TranslationErrorResponse	Unauthorized. Please check your credentials
429 Too Many Requests	TranslationErrorResponse	Too many requests
500 Internal Server Error	TranslationErrorResponse	Internal Server Error
Other Status Codes	TranslationErrorResponse	Server temporary unavailable

Security

Ocp-Apim-Subscription-Key

Provide your cognitive services subscription key here.

Type: apiKey
In: header

Examples

Get status for batch operations

Sample request

HTTP

GET {endpoint}/translator/text/batch/v1.0/batches?$top=1&$skip=0&$maxpagesize=10&ids=273622bd-835c-4946-9798-fd8f19f6bbf2&statuses=Succeeded&createdDateTimeUtcStart=2021-03-23T07:03:38.0136316Z&createdDateTimeUtcEnd=2021-03-25T07:03:38.0136316Z&$orderBy=CreatedDateTime asc

Sample response

Status code:: 401

{
  "error": {
    "code": "Unauthorized",
    "message": "User is not authorized",
    "target": "Operation",
    "innerError": {
      "code": "Unauthorized",
      "message": "Operation is not authorized"
    }
  }
}

Status code:: 429

{
  "error": {
    "code": "RequestRateTooHigh",
    "message": "User's request rate is too high",
    "target": "Operation",
    "innerError": {
      "code": "RateTooHigh",
      "message": "Request rate is too high"
    }
  }
}

Status code:: 500

{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error",
    "target": "Operation",
    "innerError": {
      "code": "InternalServerError",
      "message": "Unexpected internal server error has occurred"
    }
  }
}

Status code:: 503

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "target": "Operation",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Status code:: 200

retry-after: 30
ETag: 686897696a7c876b7e

{
  "value": [
    {
      "id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
      "createdDateTimeUtc": "2021-03-23T07:03:30.013631Z",
      "lastActionDateTimeUtc": "2021-03-26T01:00:00Z",
      "status": "Succeeded",
      "summary": {
        "total": 10,
        "failed": 1,
        "success": 9,
        "inProgress": 0,
        "notYetStarted": 0,
        "cancelled": 0,
        "totalCharacterCharged": 1000
      }
    }
  ]
}

Status code:: 400

{
  "error": {
    "code": "InvalidRequest",
    "message": "Some argument is incorrect",
    "target": "Operation",
    "innerError": {
      "code": "SASTokenInvalid",
      "message": "SAS token for storage is invalid"
    }
  }
}

Definitions

Name	Description
InnerTranslationError	New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).
Status	List of possible statuses for job or document
StatusSummary
TranslationError	This contains an outer error with error code, message, details, target and an inner error with more descriptive details.
TranslationErrorCode	Enums containing high level error codes.
TranslationErrorResponse	Contains unified error information used for HTTP responses across any Cognitive Service. Instances can be created either through Microsoft.CloudAI.Containers.HttpStatusExceptionV2 or by returning it directly from a controller.
TranslationsStatus	Translation job Status Response
TranslationStatus	Translation job status response

InnerTranslationError

Object

New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

Name	Type	Description
code	string	Gets code error string.
innerError	InnerTranslationError	New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).
message	string	Gets high level error message.
target	string	Gets the source of the error. For example it would be "documents" or "document id" in case of invalid document.

Status

Enumeration

List of possible statuses for job or document

Value	Description
NotStarted
Running
Succeeded
Failed
Cancelled
Cancelling
ValidationFailed

StatusSummary

Object

Name	Type	Description
cancelled	integer (int32)	Number of cancelled
failed	integer (int32)	Failed count
inProgress	integer (int32)	Number of in progress
notYetStarted	integer (int32)	Count of not yet started
success	integer (int32)	Number of Success
total	integer (int32)	Total count
totalCharacterCharged	integer (int64)	Total characters charged by the API

TranslationError

Object

This contains an outer error with error code, message, details, target and an inner error with more descriptive details.

Name	Type	Description
code	TranslationErrorCode	Enums containing high level error codes.
innerError	InnerTranslationError	New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).
message	string	Gets high level error message.
target	string	Gets the source of the error. For example it would be "documents" or "document id" in case of invalid document.

TranslationErrorCode

Enumeration

Enums containing high level error codes.

Value	Description
InvalidRequest
InvalidArgument
InternalServerError
ServiceUnavailable
ResourceNotFound
Unauthorized
RequestRateTooHigh

TranslationErrorResponse

Object

Contains unified error information used for HTTP responses across any Cognitive Service. Instances can be created either through Microsoft.CloudAI.Containers.HttpStatusExceptionV2 or by returning it directly from a controller.

Name	Type	Description
error	TranslationError	This contains an outer error with error code, message, details, target and an inner error with more descriptive details.

TranslationsStatus

Object

Translation job Status Response

Name	Type	Description
@nextLink	string	Url for the next page. Null if no more pages available
value	TranslationStatus[]	The summary status of individual operation

TranslationStatus

Object

Translation job status response

Name	Type	Description
createdDateTimeUtc	string (date-time)	Operation created date time
error	TranslationError	This contains an outer error with error code, message, details, target and an inner error with more descriptive details.
id	string (uuid)	Id of the operation.
lastActionDateTimeUtc	string (date-time)	Date time in which the operation's status has been updated
status	Status	List of possible statuses for job or document
summary	StatusSummary

Share via

Document Translation - Get Translations Status

URI Parameters

Request Header

Responses

Security

Ocp-Apim-Subscription-Key

Examples

Get status for batch operations

Sample request

Sample response

Definitions

InnerTranslationError

Status

StatusSummary

TranslationError

TranslationErrorCode

TranslationErrorResponse

TranslationsStatus

TranslationStatus