Document Translation - Get Documents Status

Service:: Azure AI Services

API Version:: v1.0

Returns the status for all documents in a batch document translation request.

If the number of documents in the response 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 document status held by the server 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 documents. 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).

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/{id}/documents

With optional parameters:

GET {endpoint}/translator/text/batch/v1.0/batches/{id}/documents?$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).
id	path	True	string (uuid)	Format - uuid. The operation id
$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	DocumentsStatus	Successful request and returns the status of the documents Headers Retry-After: integer ETag: string
400 Bad Request	TranslationErrorResponse	Invalid request. Check input parameters
401 Unauthorized	TranslationErrorResponse	Unauthorized. Please check your credentials
404 Not Found	TranslationErrorResponse	Resource is not found
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 Documents Status for the operation batch id

Sample request

HTTP

GET {endpoint}/translator/text/batch/v1.0/batches/727BF148-F327-47A0-9481-ABAE6362F11E/documents?$top=2&$skip=0&$maxpagesize=1&ids=273622bd-835c-4946-9798-fd8f19f6bbf2,511b6a66-a6f8-4640-83e1-48c325e9fa29&statuses=Succeeded&createdDateTimeUtcStart=2021-03-23T07:03:38.0136316Z&createdDateTimeUtcEnd=2021-03-25T07:03:38.0136316Z&$orderBy=CreatedDateTimeUtc asc

Sample response

Status code:: 401

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

Status code:: 429

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

Status code:: 500

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

Status code:: 503

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

Status code:: 404

{
  "error": {
    "code": "ResourceNotFound",
    "message": "id not found",
    "target": "Document",
    "innerError": {
      "code": "ResourceNotFound",
      "message": "Resource requested is not found"
    }
  }
}

Status code:: 200

retry-after: 30
ETag: 686897696a7c876b7e

{
  "value": [
    {
      "path": "https://myblob.blob.core.windows.net/destinationContainer/fr/mydoc.txt",
      "sourcePath": "https://myblob.blob.core.windows.net/sourceContainer/fr/mydoc.txt",
      "createdDateTimeUtc": "2021-03-23T07:03:39.013631Z",
      "lastActionDateTimeUtc": "2021-03-23T07:03:41.012452Z",
      "status": "Running",
      "to": "fr",
      "progress": 0.1,
      "id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
      "characterCharged": 0
    }
  ],
  "@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.0/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/documents?$top=1&$skip=1&$maxpagesize=1&$orderBy=CreatedDateTimeUtc%20asc&createdDateTimeUtcStart=2021-03-23T00:03:38.0136316Z&createdDateTimeUtcEnd=2021-03-25T00:03:38.0136316&statuses=Succeeded&ids=273622BD-835C-4946-9798-FD8F19F6BBF2,511B6A66-A6F8-4640-83E1-48C325E9FA29"
}

Status code:: 400

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

Definitions

Name	Description
DocumentsStatus	Documents Status Response
DocumentStatus	Document Status Response
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
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.

DocumentsStatus

Object

Documents Status Response

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

DocumentStatus

Object

Document Status Response

Name	Type	Description
characterCharged	integer (int64)	Character charged by the API
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)	Document Id
lastActionDateTimeUtc	string (date-time)	Date time in which the operation's status has been updated
path	string	Location of the document or folder
progress	number (float) minimum: 0 maximum: 1	Progress of the translation if available
sourcePath	string	Location of the source document
status	Status	List of possible statuses for job or document
to	string	To language

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

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.

Share via

Document Translation - Get Documents Status

URI Parameters

Request Header

Responses

Security

Ocp-Apim-Subscription-Key

Examples

Get Documents Status for the operation batch id

Sample request

Sample response

Definitions

DocumentsStatus

DocumentStatus

InnerTranslationError

Status

TranslationError

TranslationErrorCode

TranslationErrorResponse