Get Indexer Status (Azure Cognitive Search REST API)

The Get Indexer Status operation retrieves the current status and execution history of an indexer:

GET https://[service name].search.windows.net/indexers/[indexer name]/status?api-version=[api-version]&failIfCannotDecrypt=[true|false]
  Content-Type: application/json  
  api-key: [admin key]

URI Parameters

Parameter Description
service name Required. Set this to the unique, user-defined name of your search service.
indexer name Required. The request URI specifies the name of the indexer for which status should be returned.
api-version Required. The current version is api-version=2020-06-30. See API versions in Azure Cognitive Search for a list of available versions.
failIfCannotDecrypt Optional, defaults to true if not specified. If the indexer was created using an encryption key and the search service doesn't have access to the encryption key, retrieving indexer status fails. If false, the indexer status returned has encrypted properties replaced with "<encrypted>" placeholders.

Request Headers

The following table describes the required and optional request headers.

Fields Description
Content-Type Required. Set this to application/json
api-key Required. The api-key is used to authenticate the request to your Search service. It is a string value, unique to your service. Get requests about objects in your service must include an api-key field set to your admin key (as opposed to a query key).

You can get the api-key value from your service dashboard in the Azure portal. For more information, see Find existing keys.

Request Body

None.

Response

Status Code: 200 OK for a successful response. The response body contains information about overall indexer health status, the last indexer invocation, as well as the history of recent indexer invocations (if present).

A sample response body looks like this:

{
    "status" : "running",
    "lastResult" : {
        "status" : "success",
        "errorMessage" : null,
        "startTime" : "2014-11-26T03:37:18.853Z",
        "endTime" : "2014-11-26T03:37:19.012Z",
        "errors" : [],
        "warnings" : [],
        "itemsProcessed" : 11,
        "itemsFailed" : 0,
        "initialTrackingState" : null,
        "finalTrackingState" : null
    },
    "executionHistory" : [
        {
            "status" : "success",
            "errorMessage" : null,
            "startTime" : "2014-11-26T03:37:18.853Z",
            "endTime" : "2014-11-26T03:37:19.012Z",
            "errors" : [],
            "warnings" : [],
            "itemsProcessed" : 11,
            "itemsFailed" : 0,
            "initialTrackingState" : null,
            "finalTrackingState" : null
        },
        {
            "status" : "transientFailure",
            "errorMessage" : null,
            "startTime" : "2014-11-26T03:28:10.125Z",
            "endTime" : "2014-11-26T03:28:12.007Z",
            "errors" : [
                {
                    "key" : "",
                    "name" : "The operation name describing where the error occurred. For example, 'Enrichment.LanguageDetectionSkill.SkillName'",
                    "errorMessage" : "Document key cannot be missing or empty.",
                    "statusCode" : 400,
                    "details" : "Any additional details, such as the WebApi response if executing a custom skill failed.",
                    "documentationLink" : "A link to relevant documentation. For example, 'https://go.microsoft.com/fwlink/?linkid=2099692'""
                }
            ],
            "warnings" : [
                {
                    "key" : "document id",
                    "name" : "The operation name describing where the warning occurred. For example, 'Enrichment.LanguageDetectionSkill.SkillName'",
                    "message" : "A warning doesn't stop indexing, and is intended to inform you of certain interesting situations, like when a blob indexer truncates the amount of text extracted from a blob."
                    "details" : "Any additional details, such as the WebApi response if executing a custom skill failed.",
                    "documentationLink" : "A link to relevant documentation. For example, 'https://go.microsoft.com/fwlink/?linkid=2099692'"
                }
            ],
            "itemsProcessed" : 1,
            "itemsFailed" : 1,
            "initialTrackingState" : null,
            "finalTrackingState" : null
        }
    ]
}

Note

If the indexer was created using an encryption key, encrypted properties of the status can only be retrieved if the search service has access to the encryption key. If the search service does not have access to the encryption key, a 400 Bad Request is returned by default. Specify failIfCannotDecrypt=false to retrieve the status with "<encrypted>" placeholders replacing encrypted properties.

Indexer status

Indexer status can be one of the following values:

  • running indicates that the indexer is running normally. Note that some of the indexer executions may still be failing, so it's a good idea to check the lastResult property as well.

  • error indicates that the indexer experienced an error that cannot be corrected without human intervention. For example, the data source credentials may have expired, or the schema of the data source or of the target index has changed in a breaking way.

Indexer execution result

An indexer execution result contains information about a single indexer execution. The latest result is surfaced as the lastResult property of the indexer status. Other recent results, if present, are returned as the executionHistory property of the indexer status.

Indexer execution result contains the following properties:

  • status: The status of an execution. See Indexer execution status below for details.

  • errorMessage: Error message for a failed execution.

  • startTime: The time in UTC when this execution started.

  • endTime: The time in UTC when this execution has ended. This value is not set if the execution is still in progress.

  • errors: A list of item-level errors, if any. See the sample response above for an example. Beginning with API version 2020-06-30 each error in the list will no longer include a "status" because for the item-level errors it was always false. Beginning with API version 2020-06-30, each error in the list will contain the new properties "name", "details", and "documentationLink".

  • warnings: A list of item-level warnings, if any. See the sample response above for an example. Beginning with API version 2020-06-30, each warning in the list will contain the new properties "name", "details", and "documentationLink".

  • itemsProcessed: The number of data source items (for example, table rows) that the indexer attempted to index during this execution.

  • itemsFailed: The number of items that failed during this execution. The error provides the ID of the item that failed.

  • initialTrackingState: Always null for the first indexer execution, or if the data change tracking policy is not enabled on the data source used. If such a policy is enabled, in subsequent executions this value indicates the first (lowest) change tracking value processed by this execution.

  • finalTrackingState: Always null if the data change tracking policy is not enabled on the data source used. Otherwise, indicates the latest (highest) change tracking value successfully processed by this execution.

Indexer execution status

Indexer execution status captures the status of a single indexer execution. It can have the following values:

  • success indicates that the indexer execution has completed successfully.

  • inProgress indicates that the indexer execution is in progress.

  • transientFailure indicates that an indexer execution has failed. See errorMessage property for details. The failure may or may not require human intervention to fix it. For example, fixing a schema incompatibility between the data source and the target index requires user action, while a temporary data source downtime does not. Indexer invocations will continue per schedule, if one is defined. Note that if an indexer on a schedule hits a transientFailure status repeatedly without making progress, the indexer will begin running on a less frequent interval (up to the maximum of at least once every 24 hours) until it successfully makes progress again.

  • persistentFailure indicates that the indexer has failed in a way that requires human intervention . Scheduled indexer executions stop. After addressing the issue, use Reset Indexer (Azure Cognitive Search REST API) to restart the scheduled executions.

  • Reset indicates that the indexer has been reset by a call to Reset Indexer (Azure Cognitive Search REST API).

See also

Azure Cognitive Search REST APIs
HTTP status codes (Azure Cognitive Search)
Indexer operations (Azure Cognitive Search REST API)
Naming rules (Azure Cognitive Search)
API versions in Azure Cognitive Search