Analyze Status - Analyze Status

Get analysis status and results
Get the status of an analysis job. A job may consist of one or more tasks. Once all tasks are completed, the job will transition to the completed state and results will be available for each task.

GET {Endpoint}/text/analytics/v3.1-preview.4/analyze/jobs/{jobId}
GET {Endpoint}/text/analytics/v3.1-preview.4/analyze/jobs/{jobId}?showStats={showStats}&$top={$top}&$skip={$skip}

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).

jobId
path True
  • string

Job ID for Analyze

$skip
query
  • integer

(Optional) Set the number of elements to offset in the response. When both $top and $skip are specified, $skip is applied first.

$top
query
  • integer

(Optional) Set the maximum number of results per task. When both $top and $skip are specified, $skip is applied first.

showStats
query
  • boolean

(Optional) if set to true, response will contain request and document level statistics.

Request Header

Name Required Type Description
Ocp-Apim-Subscription-Key True
  • string

Responses

Name Type Description
200 OK

Analysis job status and metadata.

Media Types: "application/json", "text/json"

404 Not Found

Job ID not found.

Media Types: "application/json", "text/json"

500 Internal Server Error

Internal error response

Media Types: "application/json", "text/json"

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful Get Analysis job status request

Sample Request

GET {Endpoint}/text/analytics/v3.1-preview.4/analyze/jobs/{Job ID}
Ocp-Apim-Subscription-Key: {API key}

Sample Response

{
  "createdDateTime": "2020-10-01T15:00:45Z",
  "displayName": "Extracting Location & US Region",
  "expirationDateTime": "2020-10-03T15:01:03Z",
  "jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18",
  "lastUpdateDateTime": "2020-10-01T15:01:03Z",
  "status": "succeeded",
  "tasks": {
    "completed": 2,
    "failed": 0,
    "inProgress": 0,
    "total": 2,
    "entityRecognitionTasks": [
      {
        "name": "Recognize Entities (2020-04-01)",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "entities": [
                {
                  "category": "Event",
                  "confidenceScore": 0.61,
                  "length": 4,
                  "offset": 18,
                  "text": "trip"
                },
                {
                  "category": "Location",
                  "confidenceScore": 0.82,
                  "length": 7,
                  "offset": 26,
                  "subcategory": "GPE",
                  "text": "Seattle"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 9,
                  "offset": 34,
                  "subcategory": "DateRange",
                  "text": "last week"
                }
              ],
              "id": "1",
              "warnings": []
            },
            {
              "entities": [
                {
                  "category": "Location",
                  "confidenceScore": 0.52,
                  "length": 3,
                  "offset": 14,
                  "subcategory": "GPE",
                  "text": "NYC"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 8,
                  "offset": 18,
                  "subcategory": "Date",
                  "text": "tomorrow"
                }
              ],
              "id": "2",
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}
{
  "error": {
    "code": "NotFound",
    "message": "Not Found",
    "innererror": {
      "code": "JobIdNotFound",
      "message": "Job ID not found."
    }
  }
}
{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error"
  }
}

Definitions

AnalyzeJobState
Details
DocumentEntities
DocumentError
DocumentStatistics

if showStats=true was specified in the request this field will contain information about the document payload.

EntitiesResult
Entity
ErrorCodeValue

Error code.

ErrorResponse
InnerError
InnerErrorCodeValue

Error code.

object
RequestStatistics

if showStats=true was specified in the request this field will contain information about the request payload.

State
Tasks
TextAnalyticsError
TextAnalyticsWarning
WarningCodeValue

Error code.

AnalyzeJobState

Name Type Description
@nextLink
  • string
createdDateTime
  • string
displayName
  • string
errors
expirationDateTime
  • string
jobId
  • string
lastUpdateDateTime
  • string
statistics

if showStats=true was specified in the request this field will contain information about the request payload.

status
tasks

Details

Name Type Description
lastUpdateDateTime
  • string
name
  • string
status

DocumentEntities

Name Type Description
entities

Recognized entities in the document.

id
  • string

Unique, non-empty document identifier.

statistics

if showStats=true was specified in the request this field will contain information about the document payload.

warnings

Warnings encountered while processing document.

DocumentError

Name Type Description
error

Document Error.

id
  • string

Document Id.

DocumentStatistics

if showStats=true was specified in the request this field will contain information about the document payload.

Name Type Description
charactersCount
  • integer

Number of text elements recognized in the document.

transactionsCount
  • integer

Number of transactions for the document.

EntitiesResult

Name Type Description
documents

Response by document

errors

Errors by document id.

modelVersion
  • string

This field indicates which model is used for scoring.

statistics

if showStats=true was specified in the request this field will contain information about the request payload.

Entity

Name Type Description
category
  • string

Entity type.

confidenceScore
  • number

Confidence score between 0 and 1 of the extracted entity.

length
  • integer

Length for the entity text. Use of different 'stringIndexType' values can affect the length returned.

offset
  • integer

Start position for the entity text. Use of different 'stringIndexType' values can affect the offset returned.

subcategory
  • string

(Optional) Entity sub type.

text
  • string

Entity text as appears in the request.

ErrorCodeValue

Error code.

Name Type Description
InternalServerError
  • string
InvalidArgument
  • string
InvalidRequest
  • string
NotFound
  • string
ServiceUnavailable
  • string

ErrorResponse

Name Type Description
error

Document Error.

InnerError

Name Type Description
code

Error code.

details
  • object

Error details.

innererror

Inner error contains more specific information.

message
  • string

Error message.

target
  • string

Error target.

InnerErrorCodeValue

Error code.

Name Type Description
EmptyRequest
  • string
InvalidCountryHint
  • string
InvalidDocument
  • string
InvalidDocumentBatch
  • string
InvalidParameterValue
  • string
InvalidRequestBodyFormat
  • string
MissingInputRecords
  • string
ModelVersionIncorrect
  • string
UnsupportedLanguageCode
  • string

object

Name Type Description
lastUpdateDateTime
  • string
name
  • string
results
status

RequestStatistics

if showStats=true was specified in the request this field will contain information about the request payload.

Name Type Description
documentsCount
  • integer

Number of documents submitted in the request.

erroneousDocumentsCount
  • integer

Number of invalid documents. This includes empty, over-size limit or non-supported languages documents.

transactionsCount
  • integer

Number of transactions for the request.

validDocumentsCount
  • integer

Number of valid documents. This excludes empty, over-size limit or non-supported languages documents.

State

Name Type Description
cancelled
  • string
cancelling
  • string
failed
  • string
notStarted
  • string
partiallyCompleted
  • string
running
  • string
succeeded
  • string

Tasks

Name Type Description
completed
  • integer
details
entityLinkingTasks
entityRecognitionPiiTasks
entityRecognitionTasks
failed
  • integer
inProgress
  • integer
keyPhraseExtractionTasks
total
  • integer

TextAnalyticsError

Name Type Description
code

Error code.

details

Details about specific errors that led to this reported error.

innererror

Inner error contains more specific information.

message
  • string

Error message.

target
  • string

Error target.

TextAnalyticsWarning

Name Type Description
code

Error code.

message
  • string

Warning message.

targetRef
  • string

A JSON pointer reference indicating the target object.

WarningCodeValue

Error code.

Name Type Description
DocumentTruncated
  • string
LongWordsInDocument
  • string