DescribeStateMachine
Provides information about a state machine's definition, its IAM role Amazon Resource Name (ARN), and configuration.
A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN.
The following are some examples of qualified and unqualified state machine ARNs:
-
The following qualified state machine ARN refers to a Distributed Map state with a label
mapStateLabel
in a state machine namedmyStateMachine
.arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel
Note
If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with
ValidationException
. -
The following qualified state machine ARN refers to an alias named
PROD
.arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD>
Note
If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias.
-
The following unqualified state machine ARN refers to a state machine named
myStateMachine
.arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine>
This API action returns the details for a state machine version if the
stateMachineArn
you specify is a state machine version ARN.
Note
This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
Request Syntax
{
"stateMachineArn": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- stateMachineArn
-
The Amazon Resource Name (ARN) of the state machine for which you want the information.
If you specify a state machine version ARN, this API returns details about that version. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example,
stateMachineARN:1
.Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Required: Yes
Response Syntax
{
"creationDate": number,
"definition": "string",
"description": "string",
"label": "string",
"loggingConfiguration": {
"destinations": [
{
"cloudWatchLogsLogGroup": {
"logGroupArn": "string"
}
}
],
"includeExecutionData": boolean,
"level": "string"
},
"name": "string",
"revisionId": "string",
"roleArn": "string",
"stateMachineArn": "string",
"status": "string",
"tracingConfiguration": {
"enabled": boolean
},
"type": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- creationDate
-
The date the state machine is created.
For a state machine version,
creationDate
is the date the version was created.Type: Timestamp
- definition
-
The Amazon States Language definition of the state machine. See Amazon States Language.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1048576.
- description
-
The description of the state machine version.
Type: String
Length Constraints: Maximum length of 256.
- label
-
A user-defined or an auto-generated string that identifies a
Map
state. This parameter is present only if thestateMachineArn
specified in input is a qualified state machine ARN.Type: String
- loggingConfiguration
-
Type: LoggingConfiguration object
- name
-
The name of the state machine.
A name must not contain:
-
white space
-
brackets
< > { } [ ]
-
wildcard characters
? *
-
special characters
" # % \ ^ | ~ ` $ & , ; : /
-
control characters (
U+0000-001F
,U+007F-009F
)
To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 80.
-
- revisionId
-
The revision identifier for the state machine.
Use the
revisionId
parameter to compare between versions of a state machine configuration used for executions without performing a diff of the properties, such asdefinition
androleArn
.Type: String
- roleArn
-
The Amazon Resource Name (ARN) of the IAM role used when creating this state machine. (The IAM role maintains security by granting Step Functions access to AWS resources.)
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
- stateMachineArn
-
The Amazon Resource Name (ARN) that identifies the state machine.
If you specified a state machine version ARN in your request, the API returns the version ARN. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example,
stateMachineARN:1
.Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
- status
-
The current status of the state machine.
Type: String
Valid Values:
ACTIVE | DELETING
- tracingConfiguration
-
Selects whether AWS X-Ray tracing is enabled.
Type: TracingConfiguration object
- type
-
The
type
of the state machine (STANDARD
orEXPRESS
).Type: String
Valid Values:
STANDARD | EXPRESS
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidArn
-
The provided Amazon Resource Name (ARN) is not valid.
HTTP Status Code: 400
- StateMachineDoesNotExist
-
The specified state machine does not exist.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: