Skip to content
View as Markdown

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.

For a worked example, start from the capture-session action on the workflow. In the workflow schema this is modeled as ActionRule.flush_rule, whose value is a 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 and pass aggregated_action_id.

The generated DashboardService.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.