Clean Room
Documentation

Example Flow Run Workflow

This example flow run workflow is designed to demonstrate one way you can set up a flow run for a pre-existing flow. Many other workflows are possible, but we hope this one will serve as a model you can adapt to your needs.

Retrieve the flow parameters

You can use the API to retrieve the parameters of a flow and assigned datasets and then use those parameters to create flow runs.

$ curl -b token -X GET 'https://api.habu.com/v1/(cleanroomId}/cleanroom-flows/{flowId}/flow-run-parameters'

$ {
  "response": [
    {
      "nodeId": "n1234",
      "nodeQuestionName": "q1 - Clone",
      "parameterMetadataList": []
    }
  ]
}

Create a flow run

Use the nodeID to create a flow run that starts at the first node and then pauses. To complete the whole run, leave the pause level blank.

$ cat flow_run
  
$ {
  "name": "test_flow_sample_API_run",
  "flowRunParameters": [
    {
      "nodeId": "17764448-03uu-4f87-849f-27f9b37c65ca",
      "parameters": {
        "digital.exposure_date_utc_start": {
          "value": "2025-07-01",
          "parameterType": "PARTITION_PARAMETER"
        }
      }
    },
    {
      "nodeId": "17764448-03uu-4f87-849f-27f9b37c65ca",
      "parameters": {
        "digital.exposure_date_utc_end": {
          "value": "2025-07-10",
          "parameterType": "PARTITION_PARAMETER"
        }
      }
    },
    {
      "nodeId": "17764448-03uu-4f87-849f-27f9b37c65ca",
      "parameters": {
        "digital.brand": {
          "value": "generic",
          "parameterType": "RUNTIME_PARAMETER"
        }
      }
    }
  ],
  "startLevelId": 1,
  "pauseLevelId": 1
}

$ curl -b token -X POST 'https://api.habu.com/v1/cleanrooms/{cleanroomId}/cleanroom-flows/{flowId}/clean-room-flow-runs'

$ {
  "response": {
    "Id": "fr1234"
  }
}

pauseLevelId pauses a flow run at a given “level” or logical termination point. You can resume the flow with the Resume a Cleanroom Flow Run call, which uses the intermediate results from level 1 to proceed rather than rerunning the first node.

📘

Reducing Runtime

You can reduce runtime by reusing the results for calculations that are the same for every run (for example, matching RampIDs or applying persistent filters). See replay a Cleanroom Flow Run for more information.

Poll the flow run status

🚧

API Limits

You can poll the flow run status up to every 5 minutes, but we recommend that you poll once an hour.

$ curl -b token -X GET https://api.habu.com/v1/cleanrooms/{cleanroomId}/cleanroom-flows/{cleanroomFlowId}/clean-room-flow-runs/{cleanroomFlowRunId}

$ {
  "response": {
    "id": "1e0d7f4a-d6a1-4000-9e5f-41968137e825",
    "name": "API Flow run",
    "status": "COMPLETED",
    "submittedAt": "2024-11-10T18:09:16.336344-05:00",
    "completedAt": "2024-11-10T20:09:16.336344-05:00",
    "flowRunParameters": [
      {
        "nodeId": "35e94953-5e2d-4e0f-b773-42fdc81fd090",
        "parameters": []
      },
      {
        "nodeId": "35e94953-5e2d-4e0f-b773-42fdc81fd090",
        "parameters": []
      }
    ],
    "runMessage": ""
  }
}

Download the flow run results

Fetch a Cleanroom Flow Run Report retrieves the results for one node of a cleanroom flow run. The name of the node is always a required parameter.

This endpoint retrieves the results for a particular node of a cleanroom flow run. The cleanroom ID and cleanroomFlowRun ID are passed in through the request URL and the name of the node is a required request parameter.

$ curl -b token -X GET 'https://api.habu-labs.com/v1/cleanrooms/{cleanroomId}/cleanroom-flow-runs/{cleanroomFlowRunId}/report?node={node name}'

$ { "response": {
        "title": "q2 - Clone",
        "metadata": {
            "facts": [
                "Total Count"
            ],
          "dimensions": []
      	},
      	"recordStats": [
        		{
            	 "dimensions": [],
               "records": [
                  	{
                     	 "key": "Total Count",
                     	 "value": "576"
                		}
								]
  }

Delete a flow run

If a flow run should not be reused or visible once it completes or fails, you can delete the flow run in the UI.