Get current step

Poll a session's current step to discover its state and available actions

Some steps expect your backend to drive the interaction with the end-user instead of the Player — for example, collecting an OTP code and submitting it on the user's behalf. This endpoint lets you poll the session to discover which step is currently active, its state-specific data, and the actions you can submit via Submit a session action.

Not every step exposes actions here

Most steps run through the Player UI and do not expect API-driven input. For those, this endpoint returns stepType: "START" while they are running. Only steps documented as accepting mid-workflow actions — currently Phone number verification (v1) — return a populated data and actions array.

Endpoint

GET /api/v1/{environment}/sessions/{sessionId}/step

Path parameters

Parameter	Type	Required	Description
sessionId	string	Yes	The unique identifier of the session
environment	string	Yes	Environment name

Request

No request body is required for this endpoint.

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

curl https://localhost:3000/api/v1/live/sessions/0197c55f-5af6-7e3d-af9b-f2359b104be8/step \
-H "Authorization: Bearer YOUR_API_KEY"

Response

Response parameters

Parameter	Type	Description
stepType	string	Type of the currently active step (e.g. PHONE_VERIFY:v1), or START/END. See Step states below.
ticketId	string | null	One-time token to pass back in X-Ticket-Id when submitting an action for this state. null when no action is expected.
data	object	State-specific data (e.g. retry counters, expiry timestamps). Structure varies by stepType and current state; {} when empty.
actions	array	Actions currently available for this step. [] when no action is expected.
actions[].type	string	Action identifier to send as the type field in Submit a session action.
actions[].schema	object	JSON Schema describing the exact payload POST /actions expects for this action.

Always derive actions from the response

Never hardcode the list of accepted actions for a step. Always read the actions array from the latest /step response and validate your request body against each entry's schema before submitting.

Step states

stepType	ticketId	Meaning
START	null	Session created but the workflow has not started, or is running a step with no API actions
PHONE_VERIFY:v1	UUID	Phone verification is running and waiting for validateOtp or resendOtp
END	null	Workflow has ended — read the session result via Get session results

Session must be running

GET /step returns 400 Bad Request if the session has status CREATED (not yet started by the engine).

Response examples

No step waiting for input

{
  "stepType": "START",
  "ticketId": null,
  "data": {},
  "actions": []
}

PHONE_VERIFY:v1 — OTP sent, awaiting user input

{
  "stepType": "PHONE_VERIFY:v1",
  "ticketId": "fa85a81e-c935-4366-b14d-dc82fe2284ef",
  "data": {
    "otpExpiresAt": "2025-01-07T12:35:00.000Z",
    "validationRetriesLeft": 3,
    "generationRetriesLeft": 4,
    "lastValidationResult": null
  },
  "actions": [
    {
      "type": "validateOtp",
      "schema": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "const": "validateOtp" },
          "otp": { "type": "string" }
        },
        "required": ["type", "otp"]
      }
    },
    {
      "type": "resendOtp",
      "schema": {
        "type": "object",
        "properties": { "type": { "type": "string", "const": "resendOtp" } },
        "required": ["type"]
      }
    }
  ]
}

Workflow finished

{
  "stepType": "END",
  "ticketId": null,
  "data": {},
  "actions": []
}

Notes

• stepType is the only reliable signal to branch your polling logic on — data is state-specific and is not present for START or END.
• Poll every 2–3 seconds while waiting on a step. There is no server-push mechanism for API-driven steps.
• Stop polling once stepType is "END", then fetch the final outcome via Get session results.
• For the full set of states, data fields, and available actions for a specific step type, see that step's page under Platform guides.