Run your first action guide

Before we begin

Sign in to LongRun and open a terminal. We’ll use cURL, a command-line tool for making HTTP requests. The commands here use Bash syntax, so use Terminal on macOS/Linux or Git Bash/WSL on Windows.

cURL examples use shell variables such as ${API_KEY} and ${RUN_ID}. Set these to your own key and the IDs returned by LongRun. JavaScript uses variables such as apiKey; Python reads LONGRUN_API_KEY from the environment. JSON examples use ${NAME} markers that you replace before sending the body.

Requests with dynamic JSON bodies use jq to insert values safely. Install jq alongside cURL before following those examples.

1. Give your request a key

First, open API Keys in your workspace. Create a key named First API test and copy it when it appears.

This key tells LongRun which workspace the request belongs to. Wherever the commands below say API_KEY, replace that text with the key you just copied. Keep it private and use it from your backend, not code sent to your users’ browsers.

Before moving on: you have your own key ready to replace API_KEY.

2. Choose the tool for this job

Open API reference and look for HTML to PDF under PDF. We’re picking one example from the action catalog; LongRun also has actions for images, spreadsheets, media, and other file tasks.

You can browse that catalog in the docs, or run the request below to list it. For our first PDF, the important input is html: the content we want to turn into a document.

Browse available actions

curl --request GET "https://api.uselongrun.app/v1/actions" \
  --header "Authorization: Bearer ${API_KEY}"

3. Send a small piece of HTML

Look at the request below before running it. inputs.html contains a heading and a short paragraph. Under options, format selects A4 paper and print_background tells LongRun to include background colors.

Replace API_KEY, paste the command into your terminal, and run it. You should receive JSON with an id and a status. A 202 response means LongRun accepted the work; it doesn’t mean the PDF is finished yet. Copy your actual run id—we’ll use it next.

Create your first PDF

curl --request POST "https://api.uselongrun.app/v1/pdf/html-to-pdf" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "inputs": {
    "html": "<!doctype html><html><body><h1>Hello from LongRun</h1><p>Your first PDF.</p></body></html>"
  },
  "options": {
    "format": "A4",
    "print_background": true
  }
}'

Accepted response · illustrative

{
  "id": "run_example",
  "status": "queued",
  "outputs": null,
  "error": null
}

Before moving on: keep the run id from your response. The example RUN_ID will not work.

4. Wait for the result

Now let’s ask about the work we just submitted. Replace RUN_ID below with the real run id you copied, then run the command.

Look at status in the response. queued means it is waiting; running means it is being processed. Wait 2 seconds before checking again. When you see completed, you can move to the download. If you see failed or cancelled, stop and inspect the error instead.

For this exercise, stop checking after 2 minutes. That does not cancel the work—you can return to Runs to check it later.

Check the run

curl --request GET "https://api.uselongrun.app/v1/runs/${RUN_ID}" \
  --header "Authorization: Bearer ${API_KEY}"

5. Download and check the file

Once status is completed, look inside outputs.file for the file id. We used the run id to check the work; now we need the file id to retrieve what it produced.

Replace FILE_ID with that id and run the download command. It saves the LongRun file as result.pdf in your current folder. Open it and check the content. You’ve now followed a request all the way from input to a usable file. The response example below shows only the fields we need for this step.

Completed response · relevant fields only

{
  "id": "run_example",
  "status": "completed",
  "outputs": {
    "file": {
      "id": "file_result",
      "name": "result.pdf",
      "mime_type": "application/pdf"
    }
  },
  "error": null
}

Download the result

curl --fail-with-body "https://api.uselongrun.app/v1/files/${FILE_ID}/content" \
  --header "Authorization: Bearer ${API_KEY}" \
  --output result.pdf

If something goes wrong

If the request returns 401, check the API key. If the run fails, read error.message and open its details in Runs. Correct the input before submitting another run. A 202 response means accepted, not finished.

Docs

Run your first action