# List and inspect workflows

> Retrieve a bounded workflow collection, select one resource, and inspect its exact JSON:API attributes and response headers.

List a bounded set of workflows, then retrieve one resource by ID. This is a
read-only way to practice collection controls and JSON:API resource identity.
An empty collection is valid; the detail step is conditional on a workflow
already existing.

## What you will do

1. Request at most ten workflows with an explicit sort and sparse fieldset.
2. Verify `200`, `x-api-version`, `x-request-id`, and the `data` array.
3. If a workflow exists, extract its ID without logging the bearer token.
4. Retrieve that workflow at its canonical item path.

## Prerequisites

- Complete [Make your first API request](/get-started/first-api-request).
- Keep `HODOFLOW_BASE_URL` and `TOKEN` in a trusted process environment.
- Use a service account with `api_read` and an active run-as member in the
  workspace you intend to inspect.
- Install cURL and `jq`.

The workflow list reveals only objects visible in the service account's stored
workspace and allowed to its run-as member.

## Request

Request a small page. `--globoff` prevents cURL from interpreting bracketed
query keys:

```bash
WORKFLOWS_RESPONSE="$(
  curl --silent --show-error --globoff \
    --dump-header /dev/stderr \
    --header "Accept: application/vnd.api+json" \
    --header "Authorization: Bearer $TOKEN" \
    "$HODOFLOW_BASE_URL/api/json/v1/workflows?page[limit]=10&sort=name&fields[workflow]=name,is_active,version_number"
)"

printf '%s\n' "$WORKFLOWS_RESPONSE" | jq .
```

You should see a top-level `data` array containing zero to ten resources. Each
resource still has `type` and `id`; the sparse fieldset restricts attributes to
the requested public fields.

If a workflow exists, extract the first ID and retrieve it:

```bash
WORKFLOW_ID="$(printf '%s\n' "$WORKFLOWS_RESPONSE" | jq -er '.data[0].id')"

curl --silent --show-error \
  --header "Accept: application/vnd.api+json" \
  --header "Authorization: Bearer $TOKEN" \
  "$HODOFLOW_BASE_URL/api/json/v1/workflows/$WORKFLOW_ID" |
  jq .
```

Skip the detail request when `.data` is empty. Create a workflow through the
application if the next exercise requires one; do not invent an ID.

## Expected response

The collection returns `200 OK`, `x-api-version: v1`, and a non-empty
`x-request-id`. A populated response resembles:

```json
{
  "data": [
    {
      "type": "workflow",
      "id": "00000000-0000-4000-8000-000000000001",
      "attributes": {
        "name": "Order intake",
        "is_active": true,
        "version_number": 3
      }
    }
  ],
  "jsonapi": { "version": "1.0" },
  "links": {
    "next": null,
    "prev": null,
    "self": "https://hodoflow.com/api/json/v1/workflows?page[limit]=10"
  }
}
```

The detail response has one `data` object with the same `type` and `id`. Its
attributes may be broader because the second request did not send a sparse
fieldset.

## Troubleshooting

- `401`: discard the cached token, exchange once, and retry once.
- `403`: grant `api_read` or correct the run-as membership; retries cannot add access.
- `404` on the detail path: re-read the ID in the same workspace. It may be
  absent or hidden by object authorization.
- `400`/`422`: compare filter, sort, and field names with the
  [workflow reference](/reference/json-api/workflows).
- `429`: wait for `Retry-After`, then repeat the read.
- Empty `data`: authentication succeeded; create product state only if your next
  task needs it.

Unset `WORKFLOW_ID` and `WORKFLOWS_RESPONSE` when finished if local policy treats
resource data as sensitive.

## Next steps

- [Follow a workflow run](/guides/follow-workflow-run) after the workflow executes.
- [Learn pagination and filtering](/platform/pagination-filtering-sorting).
- Open the [Workflows API reference](/reference/json-api/workflows) for every operation and field.