n8n-nodes-jq-helper
An n8n community node that runs jq programs over inline JSON or a linked Apify dataset. It is backed by the jq Helper Actor on Apify and bills per event, so there are no subscriptions and no minimums.
Installation · Credentials · Operations · Output · Example workflows · Pricing · Resources
What it does
Give the node a jq filter and either raw JSON/JSONL text or the ID of an upstream Apify dataset, and it runs the filter through a real jq engine (1.8 syntax) and returns the result as n8n items. It also works as an AI Agent tool, so an agent can write and run its own jq expression on the fly to reshape data mid-workflow. Good for reshaping scraper output, flattening nested JSON, filtering arrays down to what you need, and quick one-off JSON transforms without writing a Code node.
- Run any jq 1.8 filter against inline JSON/JSONL or an Apify dataset
- Choose whether the filter applies per array element or to the whole input
- Non-object filter results are automatically wrapped in a configurable key
- Inline JSON runs are free; only dataset-linked runs are billed
Installation
Follow the n8n community nodes installation guide:
- In n8n, open Settings > Community Nodes.
- Select Install.
- Enter
n8n-nodes-jq-helperas the npm package name. - Agree to the risks of using community nodes, then select Install.
After it installs, the jq Helper node appears in the nodes panel.
n8n Cloud only allows verified community nodes. Until this node is verified, install it on a self-hosted n8n instance.
Credentials
You need a free Apify account and an API token.
- Sign in to the Apify Console.
- Open Settings > Integrations and copy your Personal API token.
- In n8n, create a new Apify API credential and paste the token.
- Use the credential's Test button to confirm it works.
The node also supports Apify OAuth2 if you prefer to connect that way.
Operations
Transform > Run jq Filter runs a jq program over inline JSON/JSONL or a linked Apify dataset.
| Parameter | Description |
|---|---|
| Jq Filter | The jq program to run (jq 1.8 syntax). Defaults to .. |
| Apply Mode | perItem: filter runs on each array element (write .field, not .[].field). wholeInput: filter receives the whole array/value (use .[] to reach elements). |
| Inline JSON / JSONL | Raw JSON or JSONL to transform. Provide this OR Dataset ID, not both. Free to run. |
| Dataset ID | ID of an Apify dataset to read items from (e.g. an upstream Actor run's default dataset). Provide this OR Inline JSON, not both. Paid: $0.01 per run. |
| Scalar Wrap Key | When the filter emits a non-object value, it's wrapped as { <wrapKey>: value }. |
| Fail on Filter Error | Whether to fail the run if the jq filter errors on any item. |
Output
This Actor's output shape is fully dynamic — it is defined entirely by the jq filter you write, so there is no fixed schema to select or simplify. Each item the filter emits is returned as its own n8n item, exactly as produced (non-object results are wrapped under the Scalar Wrap Key).
Example workflows
1. Reshape a scraper's dataset with a one-liner
- Any scraper node (e.g. a listing scraper) runs and produces a dataset.
- jq Helper: Dataset ID = the scraper run's dataset, Filter =
{title, price: .price.amount}. - Downstream nodes receive flat, renamed rows ready for a spreadsheet or database.
2. Flatten nested JSON for export
- HTTP Request node fetches a nested JSON API response.
- jq Helper: Inline JSON = the response body, Apply Mode =
wholeInput, Filter =[.results[] | {id, name: .attributes.name}]. - Google Sheets node appends the flattened rows.
3. Let an AI Agent transform data on the fly
- AI Agent node.
- Attach jq Helper as a tool.
- Ask "Extract just the email and company from this dataset." The agent writes its own jq filter, calls the node, and returns the transformed rows.
Pricing
This node calls the jq Helper Actor on Apify, which is billed pay-per-event: $0.01 per successful run that transforms a linked Apify dataset (flat fee, any size). Runs on inline JSON/JSONL input are free. No subscription, no minimums. See the Actor page for current rates.