Analyze Conversations Job Status - Analyze Conversations Job Status

Service:: Azure AI Services

API Version:: 2024-11-01

Get analysis status and results
Get the status of an analysis job. A job can consist of one or more tasks. After all tasks succeed, the job transitions to the succeeded state and results are available for each task.

GET {Endpoint}/language/analyze-conversations/jobs/{jobId}?api-version=2024-11-01

With optional parameters:

GET {Endpoint}/language/analyze-conversations/jobs/{jobId}?api-version=2024-11-01&showStats={showStats}

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoint (e.g., https://<resource-name>.api.cognitiveservices.azure.com).
jobId	path	True	string (uuid)	job ID
api-version	query	True	string minLength: 1	The API version to use for this operation.
showStats	query		boolean	(Optional) if set to true, response will contain request and document level statistics.

Responses

Name	Type	Description
200 OK	AnalyzeConversationJobState	The request has succeeded.
Other Status Codes	ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Name

Type

Description

200 OK

AnalyzeConversationJobState

The request has succeeded.

Other Status Codes

ErrorResponse

An unexpected error response.

Headers

x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

SuccessfulConversationPIIExclusionTaskStatusRequest

SuccessfulConversationPIIRedactionCharTaskStatusRequest

SuccessfulConversationPIITaskStatusRequest

SuccessfulConversationSummarizationTaskResult

SuccessfulConversationSummarizationTaskStatusRequest

SuccessfulConversationPIIExclusionTaskStatusRequest

Sample request

HTTP

GET {Endpoint}/language/analyze-conversations/jobs/c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18?api-version=2024-11-01

Sample response

Status code:: 200

{
  "createdDateTime": "2020-10-01T15:00:45Z",
  "displayName": "Redacting PII from transcribed audio",
  "expirationDateTime": "2020-10-03T15:01:03Z",
  "jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18",
  "lastUpdatedDateTime": "2022-01-25T15:01:03Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "conversationalPIIResults",
        "taskName": "Conversation PII",
        "lastUpdateDateTime": "2022-01-25T15:01:03Z",
        "status": "succeeded",
        "results": {
          "conversations": [
            {
              "id": "1",
              "conversationItems": [
                {
                  "id": "1",
                  "redactedContent": {
                    "text": "Good morning *************.",
                    "itn": "good morning *************",
                    "maskedItn": "good morning *************",
                    "lexical": "good morning *************",
                    "audioTimings": [
                      {
                        "offset": 590000,
                        "duration": 920000
                      }
                    ]
                  },
                  "entities": []
                }
              ],
              "warnings": [],
              "statistics": {
                "transactionsCount": 1
              }
            }
          ],
          "errors": [],
          "modelVersion": "2022-05-15-preview"
        }
      }
    ]
  }
}

SuccessfulConversationPIIRedactionCharTaskStatusRequest

Sample request

HTTP

GET {Endpoint}/language/analyze-conversations/jobs/c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18?api-version=2024-11-01

Sample response

Status code:: 200

{
  "createdDateTime": "2020-10-01T15:00:45Z",
  "displayName": "Redacting PII from transcribed audio",
  "expirationDateTime": "2020-10-03T15:01:03Z",
  "jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18",
  "lastUpdatedDateTime": "2022-01-25T15:01:03Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "conversationalPIIResults",
        "taskName": "Conversation PII",
        "lastUpdateDateTime": "2022-01-25T15:01:03Z",
        "status": "succeeded",
        "results": {
          "conversations": [
            {
              "id": "1",
              "conversationItems": [
                {
                  "id": "1",
                  "redactedContent": {
                    "text": "Good morning -------------.",
                    "itn": "good morning -------------",
                    "maskedItn": "good morning -------------",
                    "lexical": "good morning -------------",
                    "audioTimings": [
                      {
                        "offset": 590000,
                        "duration": 920000
                      }
                    ]
                  },
                  "entities": [
                    {
                      "category": "Person",
                      "confidenceScore": 0.91,
                      "length": 8,
                      "offset": 13,
                      "text": "john doe"
                    }
                  ]
                }
              ],
              "warnings": [],
              "statistics": {
                "transactionsCount": 1
              }
            }
          ],
          "errors": [],
          "modelVersion": "2022-05-15-preview"
        }
      }
    ]
  }
}

SuccessfulConversationPIITaskStatusRequest

Sample request

HTTP

GET {Endpoint}/language/analyze-conversations/jobs/c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18?api-version=2024-11-01

Sample response

Status code:: 200

{
  "createdDateTime": "2020-10-01T15:00:45Z",
  "displayName": "Redacting PII from transcribed audio",
  "expirationDateTime": "2020-10-03T15:01:03Z",
  "jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18",
  "lastUpdatedDateTime": "2022-01-25T15:01:03Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "conversationalPIIResults",
        "taskName": "Conversation PII",
        "lastUpdateDateTime": "2022-01-25T15:01:03Z",
        "status": "succeeded",
        "results": {
          "conversations": [
            {
              "id": "1",
              "conversationItems": [
                {
                  "id": "1",
                  "redactedContent": {
                    "text": "Good morning *************.",
                    "itn": "good morning *************",
                    "maskedItn": "good morning *************",
                    "lexical": "good morning *************",
                    "audioTimings": [
                      {
                        "offset": 590000,
                        "duration": 920000
                      }
                    ]
                  },
                  "entities": [
                    {
                      "category": "Person",
                      "confidenceScore": 0.91,
                      "length": 8,
                      "offset": 13,
                      "text": "john doe"
                    }
                  ]
                }
              ],
              "warnings": [],
              "statistics": {
                "transactionsCount": 1
              }
            }
          ],
          "errors": [],
          "modelVersion": "2022-05-15-preview"
        }
      }
    ]
  }
}

SuccessfulConversationSummarizationTaskResult

Sample request

HTTP

GET {Endpoint}/language/analyze-conversations/jobs/3e9e8518-492f-47f9-abd1-9a7468231086?api-version=2024-11-01

Sample response

Status code:: 200

{
  "displayName": "Conversation Summarization Example",
  "createdDateTime": "2022-04-01T15:00:45Z",
  "expirationDateTime": "2022-04-02T15:00:45Z",
  "jobId": "3e9e8518-492f-47f9-abd1-9a7468231086",
  "lastUpdatedDateTime": "2022-04-01T15:00:49Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "conversationalSummarizationResults",
        "lastUpdateDateTime": "2022-04-01T15:00:49Z",
        "taskName": "Conversation Summarization Task 1",
        "status": "succeeded",
        "results": {
          "conversations": [
            {
              "id": "1",
              "summaries": [
                {
                  "aspect": "chapterTitle",
                  "text": "Bug Triage",
                  "contexts": [
                    {
                      "conversationItemId": "2",
                      "offset": 4,
                      "length": 39
                    }
                  ]
                },
                {
                  "aspect": "narrative",
                  "text": "Speaker 3 believes there are 3 remaining bugs.",
                  "contexts": [
                    {
                      "conversationItemId": "2",
                      "offset": 4,
                      "length": 39
                    },
                    {
                      "conversationItemId": "3",
                      "offset": 0,
                      "length": 7
                    }
                  ]
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "latest"
        }
      }
    ]
  },
  "nextLink": "<resource-endpoint>/language/analyze-conversation/jobs/3e9e8518-492f-47f9-abd1-9a7468231086?$skip=10&$top=10"
}

SuccessfulConversationSummarizationTaskStatusRequest

Sample request

HTTP

GET {Endpoint}/language/analyze-conversations/jobs/c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18?api-version=2024-11-01

Sample response

Status code:: 200

{
  "displayName": "Analyze chat",
  "createdDateTime": "2022-04-01T15:00:45Z",
  "expirationDateTime": "2022-04-02T15:00:45Z",
  "jobId": "3e9e8518-492f-47f9-abd1-9a7468231086",
  "lastUpdatedDateTime": "2022-04-01T15:00:49Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "conversationalSummarizationResults",
        "lastUpdateDateTime": "2022-04-01T15:00:49Z",
        "taskName": "analyze 1",
        "status": "succeeded",
        "results": {
          "conversations": [
            {
              "id": "20220101meeting",
              "summaries": [
                {
                  "aspect": "issue",
                  "text": "Customer wants to cancel his subscription. Customer doesn't know how"
                },
                {
                  "aspect": "resolution",
                  "text": "pii Auto-Fortify. \npii Gamertag.\npii E-mail.\nCanceled customer's subscription"
                }
              ],
              "warnings": [],
              "statistics": {
                "transactionsCount": 1
              }
            }
          ],
          "errors": [],
          "modelVersion": "latest"
        }
      }
    ]
  },
  "nextLink": "<resource-endpoint>/language/analyze-conversation/jobs/3e9e8518-492f-47f9-abd1-9a7468231086?$skip=10&$top=10"
}

Definitions

Name	Description
AnalyzeConversationConversationPiiResult	Result from the personally identifiable information detection and redaction operation performed on a list of conversations.
AnalyzeConversationJobState	Contains the status of the submitted job for analyzing a conversation, along with related statistics.
AnalyzeConversationResultsKind	Enumeration of results for supported conversation analysis Results.
AnalyzeConversationSummarizationResult	Result for the summarization task on the conversation.
AudioTiming	Audio timing information.
ConversationalPiiResultWithResultBase	Conversation PII result item
ConversationPiiItemResult	The result from PII detection and redaction operation for each conversation.
ConversationPiiResults	The result from PII detection and redaction operation for each conversation.
ConversationRequestStatistics	if showStats=true was specified in the request, this field contains information about the request payload.
ConversationsSummaryResult	Conversations Summary Result
ConversationStatistics	If showStats=true was specified in the request, this field contains information about the conversation payload.
DocumentError	Contains details of errors encountered during a job execution.
Entity	Text that has been categorized into pre-defined classes or types such as: person, location, event, product, and organization.
Error	The error object.
ErrorCode	Human-readable error code.
ErrorResponse	Error response.
InnerErrorCode	Human-readable error code.
InnerErrorModel	An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
InputWarning	Contains details of warnings encountered during a job execution.
ItemizedSummaryContext	Context of the summary with a conversation item ID.
RedactedTranscriptContent	Transcript content response that the service generates, with all necessary personally identifiable information redacted.
RequestStatistics	if showStats=true was specified in the request this field will contain information about the request payload.
State	The status of the task at the mentioned last update time.
SummaryResult	Summary Results
SummaryResultItem	Summary Result Item
Tasks	Contains the state for the tasks that are being executed as part of the submitted job for analyzing a conversation.

AnalyzeConversationConversationPiiResult

Object

Result from the personally identifiable information detection and redaction operation performed on a list of conversations.

Name	Type	Description
kind	string: conversationalPIIResults	discriminator kind
lastUpdateDateTime	string (date-time)	The last updated time in UTC for the task.
results	ConversationPiiResults	results
status	State	The status of the task at the mentioned last update time.
taskName	string	task name

AnalyzeConversationJobState

Object

Contains the status of the submitted job for analyzing a conversation, along with related statistics.

Name	Type	Description
createdDateTime	string (date-time)	Date and time job created
displayName	string	display name
errors	Error[]	errors
expirationDateTime	string (date-time)	Date and time job expires
jobId	string (uuid)	job ID
lastUpdatedDateTime	string (date-time)	last updated date and time
nextLink	string	next link
statistics	ConversationRequestStatistics	Contains the statistics for the submitted job.
status	State	status
tasks	Tasks	Contains the state for the tasks that are being executed as part of the submitted job for analyzing a conversation.

AnalyzeConversationResultsKind

Enumeration

Enumeration of results for supported conversation analysis Results.

Value	Description
conversationalSummarizationResults	Conversational Summarization Results
conversationalPIIResults	Conversational PII Results

AnalyzeConversationSummarizationResult

Object

Result for the summarization task on the conversation.

Name	Type	Description
kind	string: conversationalSummarizationResults	discriminator kind
lastUpdateDateTime	string (date-time)	The last updated time in UTC for the task.
results	SummaryResult	results
status	State	The status of the task at the mentioned last update time.
taskName	string	task name

AudioTiming

Object

Audio timing information.

Name	Type	Description
duration	integer (int64)	Duration of word articulation, in ticks. 1 tick = 100 nanoseconds.
offset	integer (int64)	Offset from the start of speech audio, in ticks. 1 tick = 100 nanoseconds.

ConversationalPiiResultWithResultBase

Object

Conversation PII result item

Name	Type	Description
conversationItems	ConversationPiiItemResult[]	List of conversationItems
id	string	Unique, non-empty conversation identifier.
statistics	ConversationStatistics	If showStats=true was specified in the request this field will contain information about the conversation payload.
warnings	InputWarning[]	Warnings encountered in processing the document.

ConversationPiiItemResult

Object

The result from PII detection and redaction operation for each conversation.

Name	Type	Description
entities	Entity[]	Array of Entities
id	string	Id of the result
redactedContent	RedactedTranscriptContent	Transcript content response that the service generates, with all necessary personally identifiable information redacted.

ConversationPiiResults

Object

The result from PII detection and redaction operation for each conversation.

Name	Type	Description
conversations	ConversationalPiiResultWithResultBase[]	array of conversations
errors	DocumentError[]	Errors by document id.
modelVersion	string	This field indicates which model is used for scoring.
statistics	RequestStatistics	statistics

ConversationRequestStatistics

Object

if showStats=true was specified in the request, this field contains information about the request payload.

Name	Type	Description
conversationsCount	integer (int32)	Number of conversations submitted in the request.
documentsCount	integer (int32)	Number of documents submitted in the request.
erroneousConversationsCount	integer (int32)	Number of invalid documents. This includes documents that are empty, over the size limit, or in unsupported languages.
erroneousDocumentsCount	integer (int32)	Number of invalid documents. This includes empty, over-size limit or non-supported languages documents.
transactionsCount	integer (int64)	Number of transactions for the request.
validConversationsCount	integer (int32)	Number of conversation documents. This excludes documents that are empty, over the size limit, or in unsupported languages.
validDocumentsCount	integer (int32)	Number of valid documents. This excludes empty, over-size limit or non-supported languages documents.

ConversationsSummaryResult

Object

Conversations Summary Result

Name	Type	Description
id	string	Unique, non-empty conversation identifier.
statistics	ConversationStatistics	If showStats=true was specified in the request this field will contain information about the conversation payload.
summaries	SummaryResultItem[]	array of summaries
warnings	InputWarning[]	Warnings encountered in processing the document.

ConversationStatistics

Object

If showStats=true was specified in the request, this field contains information about the conversation payload.

Name	Type	Description
transactionsCount	integer (int32)	Number of text units for the request.

DocumentError

Object

Contains details of errors encountered during a job execution.

Name	Type	Description
error	Error	Error encountered.
id	string	The ID of the input document.

Entity

Object

Text that has been categorized into pre-defined classes or types such as: person, location, event, product, and organization.

Name	Type	Description
category	string	Entity type.
confidenceScore	number (double)	Confidence score between 0 and 1 of the extracted entity.
length	integer (int32)	Length for the entity text. Use of different 'stringIndexType' values can affect the length returned.
offset	integer (int32)	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.

Error

Object

The error object.

Name	Type	Description
code	ErrorCode	One of a server-defined set of error codes.
details	Error[]	An array of details about specific errors that led to this reported error.
innererror	InnerErrorModel	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

ErrorCode

Enumeration

Human-readable error code.

Value	Description
InvalidRequest	Invalid request error
InvalidArgument	Invalid argument error
Unauthorized	Unauthorized access error
Forbidden	Forbidden access error
NotFound	Not found error
ProjectNotFound	Project not found error
OperationNotFound	Operation not found error
AzureCognitiveSearchNotFound	Azure Cognitive Search not found error
AzureCognitiveSearchIndexNotFound	Azure Cognitive Search index not found error
TooManyRequests	Too many requests error
AzureCognitiveSearchThrottling	Azure Cognitive Search throttling error
AzureCognitiveSearchIndexLimitReached	Azure Cognitive Search index limit reached error
InternalServerError	Internal server error
ServiceUnavailable	Service unavailable error
Timeout	Timeout error
QuotaExceeded	Quota exceeded error
Conflict	Conflict error
Warning	Warning error

ErrorResponse

Object

Error response.

Name	Type	Description
error	Error	The error object.

InnerErrorCode

Enumeration

Human-readable error code.

Value	Description
InvalidRequest	Invalid request error
InvalidParameterValue	Invalid parameter value error
KnowledgeBaseNotFound	Knowledge base not found error
AzureCognitiveSearchNotFound	Azure Cognitive Search not found error
AzureCognitiveSearchThrottling	Azure Cognitive Search throttling error
ExtractionFailure	Extraction failure error
InvalidRequestBodyFormat	Invalid request body format error
EmptyRequest	Empty request error
MissingInputDocuments	Missing input documents error
InvalidDocument	Invalid document error
ModelVersionIncorrect	Model version incorrect error
InvalidDocumentBatch	Invalid document batch error
UnsupportedLanguageCode	Unsupported language code error
InvalidCountryHint	Invalid country hint error

InnerErrorModel

Object

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name	Type	Description
code	InnerErrorCode	One of a server-defined set of error codes.
details	object	Error details.
innererror	InnerErrorModel	An object containing more specific information than the current object about the error.
message	string	Error message.
target	string	Error target.

InputWarning

Object

Contains details of warnings encountered during a job execution.

Name	Type	Description
code	string	Warning code.
message	string	Warning message.
targetRef	string	A JSON pointer reference indicating the target object.

ItemizedSummaryContext

Object

Context of the summary with a conversation item ID.

Name	Type	Description
conversationItemId	string	Reference to the ID of ConversationItem.
length	integer (int32)	The length of the context. Use of different 'stringIndexType' values can affect the length returned.
offset	integer (int32)	Start position for the context. Use of different 'stringIndexType' values can affect the offset returned.

RedactedTranscriptContent

Object

Transcript content response that the service generates, with all necessary personally identifiable information redacted.

Name	Type	Description
audioTimings	AudioTiming[]	List of redacted audio segments.
itn	string	Redacted output for input in inverse-text-normalized format.
lexical	string	Redacted output for input in lexical format.
maskedItn	string	Redacted output for input in masked inverse-text-normalized format.
text	string	Redacted output for input in text (Microsoft's speech-to-text 'display') format.

RequestStatistics

Object

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

Name	Type	Description
documentsCount	integer (int32)	Number of documents submitted in the request.
erroneousDocumentsCount	integer (int32)	Number of invalid documents. This includes empty, over-size limit or non-supported languages documents.
transactionsCount	integer (int64)	Number of transactions for the request.
validDocumentsCount	integer (int32)	Number of valid documents. This excludes empty, over-size limit or non-supported languages documents.

State

Enumeration

The status of the task at the mentioned last update time.

Value	Description
notStarted	Not started state
running	Running state
succeeded	Succeeded state
partiallyCompleted	Partially completed state
failed	Failed state
cancelled	Cancelled state
cancelling	Cancelling state

SummaryResult

Object

Summary Results

Name	Type	Description
conversations	ConversationsSummaryResult[]	array of conversations
errors	DocumentError[]	Errors by document id.
modelVersion	string	This field indicates which model is used for scoring.
statistics	RequestStatistics	statistics

SummaryResultItem

Object

Summary Result Item

Name	Type	Description
aspect	string	aspect
contexts	ItemizedSummaryContext[]	Context list of the summary.
text	string	text

Tasks

Object

Contains the state for the tasks that are being executed as part of the submitted job for analyzing a conversation.

Name	Type	Description
completed	integer (int32)	Count of tasks that finished successfully.
failed	integer (int32)	Count of tasks that failed.
inProgress	integer (int32)	Count of tasks that are currently in progress.
items	AnalyzeConversationJobResult[]: AnalyzeConversationConversationPiiResult[] AnalyzeConversationSummarizationResult[]	List of results from tasks (if available).
total	integer (int32)	Total count of tasks submitted as part of the job.

Share via

Analyze Conversations Job Status - Analyze Conversations Job Status

URI Parameters

Responses

Security

Ocp-Apim-Subscription-Key

OAuth2Auth

Scopes

Examples

SuccessfulConversationPIIExclusionTaskStatusRequest

Sample request

Sample response

SuccessfulConversationPIIRedactionCharTaskStatusRequest

Sample request

Sample response

SuccessfulConversationPIITaskStatusRequest

Sample request

Sample response

SuccessfulConversationSummarizationTaskResult

Sample request

Sample response

SuccessfulConversationSummarizationTaskStatusRequest

Sample request

Sample response

Definitions

AnalyzeConversationConversationPiiResult

AnalyzeConversationJobState

AnalyzeConversationResultsKind

AnalyzeConversationSummarizationResult

AudioTiming

ConversationalPiiResultWithResultBase

ConversationPiiItemResult

ConversationPiiResults

ConversationRequestStatistics

ConversationsSummaryResult

ConversationStatistics

DocumentError

Entity

Error

ErrorCode

ErrorResponse

InnerErrorCode

InnerErrorModel

InputWarning

ItemizedSummaryContext

RedactedTranscriptContent

RequestStatistics

State

SummaryResult

SummaryResultItem

Tasks