Postman Collection

The collection centralizes all API endpoints with pre-configured environment variables, ready-to-use Bearer authentication, and examples of the most common parameters. It lets you explore and test the API without building requests from scratch.

It covers the five API resources organized in folders:

Folder	Endpoints	Description
Health	1	Service status
DAGs	4	Listing, statistics, timeline, and run search
Runs	2	Summary and event payload for a specific run
Phases	5	Metadata, data, logs, and errors per phase — with NDJSON streaming
Artifacts	2	Listing and download of artifacts generated by a run

Import the collection

Download the file: hub-log-middleware.postman_collection.json
In Postman, click Import.
Drag the downloaded file or select it from the file browser.
The collection will appear in your left panel under Hub Log Middleware.

Configure variables

Before making any request, configure the collection variables. Click the collection name and select the Variables tab:

Variable	Description	Example
`baseUrl`	Base service URL, includes the `/api/v1` prefix	`https://one.fracttal.com/hub/api/v1`
`token`	Authentication Bearer token (without the `Bearer` prefix)	`eyJhbGci...`
`dag_id`	DAG identifier to query	`my-example-dag`
`run_date`	Run date in `YYYY-MM-DD` format	`2026-05-01`
`run_id`	Full run identifier	`scheduled__2026-05-01T00:00:00+00:00`
`phase`	Run phase	`extract`, `transform`, `load` or `event`

Authentication is configured at the collection level: all requests inherit the token automatically from the token variable. It only needs to be set once.

Collection structure

Health

Verifies the service is active and available before making any query.

Name	Method	Path
Health check	`GET`	`/health`

Expected response (200):

{
  "status": "healthy",
  "app_name": "Hub Log Middleware",
  "version": "1.0.0",
  "environment": "production"
}

Use it as a first step to confirm the service responds and your baseUrl is correctly configured.

DAGs

Allows browsing the DAGs available for your company and exploring their runs.

Name	Method	Path
List DAGs	`GET`	`/dags`
Run statistics for a DAG	`GET`	`/dags/{dag_id}/stats`
Run timeline for a DAG	`GET`	`/dags/{dag_id}/timeline`
Search runs for a DAG	`GET`	`/dags/{dag_id}/runs`

List DAGs — returns all DAGs accessible for the token's company. The dag_id field here is the one you should save in the dag_id variable.

Run statistics — returns counters grouped by status (success, failed, running) for a date range. The start_date and end_date parameters use YYYY-MM-DD format and are pre-loaded in the request.

Run timeline — returns runs sorted chronologically to build Gantt or calendar visualizations. Accepts the same date parameters as statistics.

Search runs — searches paginated runs with limit and offset. From here you get run_date and run_id to query the Runs and Phases endpoints.

Runs

Returns the details of a specific run identified by dag_id + run_date + run_id.

Name	Method	Path
Run summary	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}`
Event payload	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/event`

Run summary — returns the run summary: overall status, duration, completed phases, generated artifacts, and row processing metrics.

Event payload — returns the original event payload that triggered the run (e.g., the Airflow trigger message). Useful for debugging what input data the ETL received.

Phases

Access the details of each phase (extract, transform, load, event) of a specific run.

Name	Method	Path
Phase metadata	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}`
Phase data rows	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/data`
Phase logs	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/logs`
Phase logs (stream NDJSON)	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/logs`
Phase errors	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/phases/{phase}/errors`

Phase metadata — returns the phase summary: status, start/end times, number of rows processed, and number of attempts (attempt). The attempt parameter allows querying previous retries.

Phase data rows — returns the data rows processed during the phase, paginated with page and limit. Allows inspecting what records the ETL processed.

Phase logs — returns the structured logs for the phase in paginated JSON format. Accepts the optional parameters level (filter by log level) and keyword (free-text search).

Phase logs — stream NDJSON — same path as Phase logs but the Accept: application/x-ndjson header activates streaming mode. The server sends each log line as a JSON object separated by newline (NDJSON), allowing large-volume log processing without loading the entire response into memory. This request already has the header configured.

How to test the stream

In Postman, select the Phase logs (stream NDJSON) request and click Send. You will see the response arrive progressively in the bottom panel. To consume it programmatically, use requests with stream=True or fetch with ReadableStream.

Phase errors — returns only log records with level ERROR or CRITICAL, paginated. It is a quick shortcut to see what failed without manually filtering.

Artifacts

Lists and downloads the artifacts (files) generated by a run: reports, exports, data snapshots, etc.

Name	Method	Path
List artifacts	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/artifacts`
Get artifact presigned URL	`GET`	`/dags/{dag_id}/runs/{run_date}/{run_id}/artifacts/{artifact_kind}`

List artifacts — returns the available artifacts for the run, with their artifact_kind (type), size, and generation date.

Get artifact presigned URL — returns a time-limited (~15 min) S3 pre-signed URL to download the artifact directly from the browser or with curl without additional authentication. Replace :artifact_kind with the value returned by List artifacts.

Recommended query flow

To reach the logs for a specific phase from scratch:

1. Health check          → confirm the service responds
         ↓
2. List DAGs             → get the dag_id of the ETL you want
         ↓
3. Search runs           → search by date range → get run_date and run_id
         ↓
4. Run summary           → confirm the overall run status
         ↓
5. Phase logs / errors   → query the logs for the failed phase
         ↓
6. List artifacts        → download artifacts if any

For quick diagnosis of a known failure, you can jump directly to step 5 if you already have dag_id, run_date, run_id, and phase.

Disabled parameters

Some requests include disabled parameters (marked as inactive in Postman). They are optional and ready to activate without writing them from scratch:

Request	Disabled parameter	When to activate
Phase logs	`level`	Filter by level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
Phase logs	`keyword`	Free-text search in the log message
Search runs	`status`	Filter runs by status: `success`, `failed`, `running`
Run statistics	`status`	Filter counters by specific status

To activate a parameter, open it in the Params tab of the request and check the checkbox on the left.

Common troubleshooting

401 Unauthorized — the token expired or is incorrect. Update the token variable with a fresh token.

403 Forbidden — the token does not contain id_company. Verify you are using a user or OAuth2 token generated correctly (not a service token without a company).

404 Not Found on runs or phases — the run_id contains special characters (:, +, /). Make sure it is URL-encoded. Postman encodes it automatically if you leave it in the variable without manually encoding.

429 Too Many Requests — the limit of 1,200 requests/minute per IP or 60/minute per token was reached. Wait the time indicated in the Retry-After header and retry.

Empty response in Phase data rows — the phase processed no rows or the specified attempt does not exist. Check the number of attempts in Phase metadata.

NDJSON stream not arriving in Postman — some corporate proxies or older versions of Postman do not handle streaming well. If you don't see the response arriving line by line, try from curl:

curl -N "{{baseUrl}}/dags/{{dag_id}}/runs/{{run_date}}/{{run_id}}/phases/{{phase}}/logs?attempt=1" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/x-ndjson"