---
title: Action IDs
---

# Action IDs

Action IDs are opaque server-generated identifiers for workflow action outputs. As workflows are created
the server will respond with the action IDs for the actions which can be used to ask for data related to this
action.

Action IDs exist in order to allow reuse of collected data between workflows: the action IDs are inferred from the
workflow shape, ensuring that overlapping workflows do not have to collect redundant data.

## Raw vs aggregated forms

The API uses two closely related forms:

- **`action_id`** is the raw action identifier used to scope action-backed queries such as captured
  sessions.
- **`aggregated_action_id`** is the chart-series form used when querying a specific aggregated
  series. In the generated examples this appears as `count/<action-id>`.

Treat both as opaque values. Do not try to generate them yourself beyond passing through the exact
values returned by workflow-related APIs or the UI.

## Query flow

### 1. Start from a workflow-backed identifier

Use a workflow response, chart metadata response, or the UI to identify the action output you care
about. For metric-chart actions, this often means starting from an `aggregated_id` shown in a
workflow-shaped response.

### 2. Use the raw action ID for action-scoped data

When an API asks for `action_id`, pass the raw ID to scope the result to one workflow action.

A common example is fetching captured sessions for a specific action with
[WorkflowDataService.FetchCapturedSessions](../../api/bitdrift_public_unary_workflows_v1_WorkflowDataService.md#FetchCapturedSessions).

For a worked example, start from the capture-session action on the workflow. In the workflow schema
this is modeled as
[`ActionRule.flush_rule`](../../api/bitdrift_public_unary_workflows_v1_ActionRule.md#bitdrift.public.unary.workflows.v1.ActionRule),
whose value is a
[`RuleFlushConfiguration`](../../api/bitdrift_public_unary_workflows_v1_Rule.md#bitdrift.public.unary.workflows.v1.Rule.RuleFlushConfiguration).
That object contains a server-generated `id` specifically documented as the identifier you can use
to query for sessions that arrive at that rule action.

Example workflow-side value:

```json
{
  "flush_rule": {
    "id": "fkQ1PfAZhdYvJexzY6DYuoYCZTEaWO0Y7spxwjr7akc",
    "match_id": "_i1yUnHjKfmWpCaD5Tazo"
  }
}
```

Using that `RuleFlushConfiguration.id`, the follow-up query is:

```bash
curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.explorations.v1.WorkflowDataService/FetchCapturedSessions \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": "fkQ1PfAZhdYvJexzY6DYuoYCZTEaWO0Y7spxwjr7akc",
    "page": 1,
    "per_page": 25,
    "time_range": {
      "relative_time_range": {
        "duration": "3600s",
        "offset": "3600s"
      }
    }
  }'
```

That request narrows the captured-session query to the sessions produced by that specific
capture-session action instead of querying globally across all matching sessions.

### 3. Use the aggregated form when querying a chart series

When a chart query needs to target a specific workflow-backed series, wrap the ID in a
[ChartIdentifier.WorkflowChart](../../api/bitdrift_public_unary_charts_v1_ChartIdentifier.md#bitdrift.public.unary.charts.v1.ChartIdentifier.WorkflowChart)
and pass `aggregated_action_id`.

The generated
[DashboardService.GetChartsData](../../api/bitdrift_public_unary_dashboards_v1_DashboardService.md#GetChartsData)
example shows the pattern:

```bash
curl -X POST https://api-public.bitdrift.io/bitdrift.public.unary.dashboards.v1.DashboardService/GetChartsData \
  -H "x-bitdrift-api-key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "charts": [
      {
        "chart_id": {
          "workflow": {
            "workflow_id": "DFg5",
            "chart_rule_id": "_i1yUnHjKfmWpCaD5Tazo",
            "aggregated_action_id": "count/fkQ1PfAZhdYvJexzY6DYuoYCZTEaWO0Y7spxwjr7akc"
          }
        }
      }
    ],
    "time_range": {
      "relative_time_range": {
        "duration": "3600s",
        "offset": "3600s"
      }
    }
  }'
```

In that call:

- `workflow_id` identifies the workflow.
- `chart_rule_id` identifies the chart-producing action rule in that workflow.
- `aggregated_action_id` identifies the specific series derived from that action output.

## Practical guidance

If you are building against the API:

1. Read the workflow or chart metadata you already have.
2. Capture the returned raw or aggregated action-linked ID exactly as-is.
3. Reuse that value in downstream query calls instead of trying to infer or synthesize one.

## Related reference

- [API Services](../../api/services.md)
- [Workflow](../../api/bitdrift_public_unary_workflows_v1_Workflow.md)
- [ActionRule](../../api/bitdrift_public_unary_workflows_v1_ActionRule.md)
- [GetWorkflowResponse](../../api/bitdrift_public_unary_workflows_v1_GetWorkflowResponse.md)
- [WorkflowDataService](../../api/bitdrift_public_unary_workflows_v1_WorkflowDataService.md)
- [FetchCapturedSessionsRequest](../../api/bitdrift_public_unary_workflows_v1_FetchCapturedSessionsRequest.md)
- [DashboardService](../../api/bitdrift_public_unary_dashboards_v1_DashboardService.md)
- [ChartIdentifier](../../api/bitdrift_public_unary_charts_v1_ChartIdentifier.md)