# List action invocations (/en/docs/api/native/automation/listActionInvocations)





List this action’s invocations, filtering by status, revision, calling definition and time. Results identify the run and call site.

`GET /automation/v1/actions/{ns}/{name}/invocations`

## Authentication [#authentication]

`Authorization: Bearer $PRAXIS_API_KEY`

## Request fields [#request-fields]

| Parameter | Type | Description |
| --- | --- | --- |
| path: ns | `string` | required; Namespace, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. praxis is read-only. |
| path: name | `string` | required; Name, folded to lowercase; matches [a-z0-9][a-z0-9._-]{0,63}. |
| query: limit | `integer` | optional; Page size: integer 1–100, default 20. minimum: 1; maximum: 100 |
| query: cursor | `string` | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"[]` | optional; Comma-separated statuses: running, completed, faulted, cancelled; omit for all. |
| query: revision | `string` | optional; Action revision ID (actr_); the query parameter filters invocation records. |
| query: caller | `string` | optional; Exact calling script or workflow name, in ns/name format. |
| query: run_kind | `"script"` / `"workflow"` | optional; Calling run kind: script or workflow. |
| query: created_at[gte] | `string` | optional; Inclusive creation-time lower bound in RFC 3339 with timezone, e.g. 2026-10-01T00:00:00Z. format: "date-time" |

## Examples [#examples]

[SDK installation and example environment](/en/docs/api/native/automation)

Set these environment variables to your own resources:

| Variable | Source |
| --- | --- |
| ACTION_NAME | [name returned by creating an action](/en/docs/api/native/automation/createAction) |

```bash
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/invocations" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

```typescript
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.invocations.list({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  }
});
console.log(result);
```

## Response [#response]

### HTTP 200 [#http-200]

Success

`application/json`

| Field | Type | Description |
| --- | --- | --- |
| data | `object[]` | required; Invocation records of the action on this page, ordered by created_at descending, then id descending. |
| data[].id | `string` | required; Invocation identity without a separate inv_ prefix: scripts use run_id:seq (run ID and call sequence); workflows use the task execution key plus attempt. Treat it as opaque. |
| data[].created_at | `string` | required; Time the invocation record was created (RFC 3339 UTC). |
| data[].started_at | `null` / `string` | required; Time the action started executing, or null if it has not started. |
| data[].ended_at | `null` / `string` | required; Time the action finished, or null while it is still running. |
| data[].status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| data[].duration_ms | `null` / `number` | required; Execution time in milliseconds, or null until it finishes. |
| data[].revision | `string` | required; Id (actr_) of the action revision that executed. |
| data[].run | `object` | required; The run that made this invocation: {id, kind, definition, number, source_digest}. no additional fields. |
| data[].run.id | `string` | required; Id (run_) of the run that made the call; use it to read that run. |
| data[].run.kind | `"script"` / `"workflow"` | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| data[].run.definition | `null` / `object` | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs. |
| data[].run.definition (variant 2).namespace | `string` | required; Namespace of the script or workflow. |
| data[].run.definition (variant 2).name | `string` | required; Name of the script or workflow. |
| data[].run.number | `null` / `number` | required; Sequence number of the run within its script or workflow; null for ad-hoc runs. |
| data[].run.source_digest | `null` / `string` | required; Digest of the source of an ad-hoc run; null for runs started from a published definition. |
| data[].site | `object` / `object` | required; Where the invocation happened: a call in a script (kind=call with seq) or a workflow step (kind=task with reference and iteration). |
| data[].site (variant 1).kind | `"call"` | required; Always call: made by a call in a script. |
| data[].site (variant 1).seq | `number` | required; Sequence number of the call within the script run; matches Call.seq. |
| data[].site (variant 2).kind | `"task"` | required; Always task: made by a workflow step. |
| data[].site (variant 2).reference | `string` | required; JSON Pointer of the step inside the workflow document; matches Task.reference. |
| data[].site (variant 2).iteration | `number[]` | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| data[].error | `null` / `object` | required; {code, message} of the failure, or null when it succeeded or is still running. |
| data[].error (variant 2).code | `string` | required; Error code, such as a code the action declares or a platform error code. |
| data[].error (variant 2).message | `string` | required; Human-readable error message. |
| data[].result_preview | `null` / `string` | required; Single-line preview of the returned value, truncated on the server; null if unfinished or failed. |
| data[].request_id | `string` / `null` | required; Downstream response X-Request-Id, or null when absent; use it to trace failed invocations. |
| next_cursor | `null` / `string` | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |

### Measured response [#measured-response]

HTTP 200

```json
{
  "data": [],
  "next_cursor": null
}
```

## Errors [#errors]

| HTTP | Codes and description |
| --- | --- |
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | ACTION_NOT_FOUND: The action does not exist or is not visible to this tenant; a same-name script/workflow adds a hint pointing to its endpoint. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

[Authentication and common errors](/en/docs/api/errors) · Retain the `X-Request-Id` response header for troubleshooting.