get-async-operation

dci get-async-operation <operationId>

Returns the current status of an async report operation. Non-terminal operations (pending, running) include a Retry-After header suggesting when to poll again. This endpoint does not return result data — once status is "succeeded", fetch the result from the operation's results endpoint. When status is "failed", the error field contains an RFC 9457-shaped error. Returns 404 if the operationId does not exist, belongs to a different tenant, or has expired.

• operationId — The unique ID of the async operation to poll.

Examples

# Check where a background report run stands.
dci get-async-operation <operation-id>

`status` is one of pending, running, succeeded, failed, or canceled, with `createTime` and `expireBy`; a failed operation carries an `error` object. The rows are not here: fetch them with `dci get-async-operation-results`.

# Poll from a script until the operation leaves pending or running.
dci get-async-operation <operation-id> --output json | jq -r .status

# Just the status and error, as JSON.
dci get-async-operation <operation-id> --fields status,error --output json

Output

OK — current operation state. The Retry-After response header is present only on pending/running responses.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Field	Type	Description
operationId	string	Unique identifier for the operation.
status	string	Current lifecycle status of the operation. One of: "pending", "running", "succeeded", "failed", "canceled".
createTime	string (date-time)	Time the operation was created.
expireBy	string (date-time)	Time after which the operation record may be deleted.
error	object	Error describing why an async operation failed. Present only when status is "failed".
error.title	string
error.code	string	Stable machine-readable error code.
error.status	integer
error.detail	string

Raw JSON schema

{
  "type": "object",
  "description": "Response envelope for polling an async report operation. Does not include result data — once status is \"succeeded\", fetch the result from the operation's results endpoint.",
  "required": [
    "operationId",
    "status",
    "createTime",
    "expireBy"
  ],
  "properties": {
    "operationId": {
      "type": "string",
      "description": "Unique identifier for the operation."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "succeeded",
        "failed",
        "canceled"
      ],
      "description": "Current lifecycle status of the operation."
    },
    "createTime": {
      "type": "string",
      "format": "date-time",
      "description": "Time the operation was created."
    },
    "expireBy": {
      "type": "string",
      "format": "date-time",
      "description": "Time after which the operation record may be deleted."
    },
    "error": {
      "type": "object",
      "description": "Error describing why an async operation failed. Present only when status is \"failed\".",
      "required": [
        "title",
        "code",
        "status"
      ],
      "properties": {
        "title": {
          "type": "string",
          "example": "Query result set is too large"
        },
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code.",
          "example": "result_too_large"
        },
        "status": {
          "type": "integer",
          "example": 413
        },
        "detail": {
          "type": "string"
        }
      }
    }
  }
}

Errors

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping

HTTP status	Exit code	Error code	Meaning
400	30	VALIDATION_ERROR	The arguments or request body were rejected. Review the command's flags and payload.
401	10	AUTHENTICATION_FAILED	Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
403	11	PERMISSION_DENIED	The DoiT user or the active customer context does not have access.
404	20	RESOURCE_NOT_FOUND	The requested resource does not exist. Check the identifier argument.
500	40	API_SERVER_ERROR	The API failed to process the request. Retryable; contact DoiT support if it persists.

Related

• get-async-operation-results — Get results of an async report run operation
• cancel-async-operation — Cancel an async report run operation
• async-run-inline — Run a report asynchronously
• async-run-report-by-id — Run a saved report asynchronously
• API reference: GET /analytics/v1/reports/operations/{operationId}

Aliases: getasyncoperation