Skip to content

ALCF IRI API

The ALCF Facility API (IRI API) provides programmatic access to ALCF resources. This page covers authentication setup and usage examples. For questions or support, please contact ALCF Support. The OpenAPI specification for V1 and V2 can be found at https://api.alcf.anl.gov/api/v1/openapi.json and https://api.alcf.anl.gov/api/v2/openapi.json, respectively.

Access

The ALCF IRI API is available to all users who can authenticate with their ALCF credentials.

Getting Your API Token

1. Setup Your Environment

Create a Python (>=3.10) environment with uv, venv, or conda. See Python Environments for the options. Then install alcf-tokens:

pip install alcf-tokens
pip install globus-sdk

wget https://raw.githubusercontent.com/argonne-lcf/alcf-facility-api-token/refs/heads/main/alcf_facility_api_globus_token.py
# If `wget` is unavailable on your system, try `curl -O` instead.

2. Authenticate

Generate the authentication flow URL with the command below. Copy-paste the URL to your browser, authenticate with your ALCF credentials, and copy-paste the resulting authorization code in your terminal.

alcf-tokens login iri
python alcf_facility_api_globus_token.py authenticate

Test your token with the following:

alcf-tokens test-token iri

If your token is authorized to use the IRI API, you should see "ready": true. If you have issues, make sure to logout from Globus at app.globus.org/logout, clear your browser cache or use an incognito window, and try to re-authenticate.

3. Retrieve Your Access Token

You can programmatically retrieve your access token either from your terminal or from Python.

# Shell
access_token=$(alcf-tokens get-token iri)
# Python
from alcf_tokens.auth import get_access_token
access_token = get_access_token("iri")
# Shell
access_token=$(python alcf_facility_api_globus_token.py get_access_token)
# Python
from alcf_facility_api_globus_token import get_access_token
access_token = get_access_token()

Token Validity

  • Access tokens are valid for 48 hours. The token retrieval commands will automatically refresh your token if it has expired.
  • Refreshed tokens are authorized for up to 7 days, after which you will need to manually re-authenticate.

API Usage Examples

This section provides simple examples on how to interface with the API as a starting point. A complete list of input arguments, filters, and capabilities can be found on the Swagger documentation.

Rendering

If available on your machine, you can add | jq at the end of your cURL commands to pretty-print the JSON output.

API v1

These examples use API v2. API v1 is still available: for the status, compute, task, and account examples, replace /api/v2/ with /api/v1/. Filesystem requests changed more; see Filesystem.

1. Status

1.1. Resources

Query the status of all available resources.

#!/bin/bash
curl -X GET "https://api.alcf.anl.gov/api/v2/status/resources"
import requests
response = requests.get("https://api.alcf.anl.gov/api/v2/status/resources")
print(response.status_code)
print(response.json())
1.2. Specific Resource

Query a specific resource (e.g. Polaris) by specifying its resource ID.

#!/bin/bash
curl -X GET "https://api.alcf.anl.gov/api/v2/status/resources/55c1c993-1124-47f9-b823-514ba3849a9a"
import requests
response = requests.get("https://api.alcf.anl.gov/api/v2/status/resources/55c1c993-1124-47f9-b823-514ba3849a9a")
print(response.status_code)
print(response.json())
1.3. Facility

Query the ALCF Facility metadata.

#!/bin/bash
curl -X GET "https://api.alcf.anl.gov/api/v2/facility"
import requests
response = requests.get("https://api.alcf.anl.gov/api/v2/facility")
print(response.status_code)
print(response.json())

2. Compute

Currently Supported Compute Resources

  • Aurora
  • Polaris
  • Crux
2.1. Submit a Job

Submits a new job to the scheduler on the target compute resource.

For Aurora, use "custom_attributes": {"filesystems": "flare"}

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Polaris
resource_id="55c1c993-1124-47f9-b823-514ba3849a9a"

curl -X POST "https://api.alcf.anl.gov/api/v2/compute/job/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{
           "executable": "/bin/bash",
           "arguments": ["-lc", "echo Start; sleep 10; echo End"],
           "name": "my_job",
           "stdout_path": "/home/<username>/logs",
           "stderr_path": "/home/<username>/logs",
           "environment": {"MY_ENV_NAME": "my environment value"},
           "resources": {
               "node_count": 1,
               "cpu_cores_per_process": 64
           },
           "attributes": {
               "duration": 300,
               "queue_name": "<queue>",
               "account": "<project>",
               "custom_attributes": {"filesystems": "home:eagle"}
           }
         }'
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Polaris
resource_id = "55c1c993-1124-47f9-b823-514ba3849a9a"

# Equivalent to the body of a `qsub` script (excluding `#PBS` directives)
commands = "echo Start; sleep 10; echo End"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/compute/job/{resource_id}",
    json={
        "executable": "/bin/bash",
        "arguments": ["-lc", commands],
        "name": "my_job",
        "stdout_path": "/home/<username>/logs",
        "stderr_path": "/home/<username>/logs",
        "environment": {"MY_ENV_NAME": "my environment value"},
        "resources": {
            "node_count": 1,
            "cpu_cores_per_process": 64
        },
        "attributes": {
            "duration": 300,
            "queue_name": "<queue>",
            "account": "<project>",
            "custom_attributes": {"filesystems": "home:eagle"}
        }
    },
    headers=headers
)

print(response.status_code)
print(response.json())

Note

cpu_cores_per_process sets the number of CPU cores requested on each node (PBS ncpus). If omitted, each node gets all of its CPU cores.

2.2. List Jobs

Returns a paginated list of jobs on the target resource. Set historical to true to include completed jobs.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Polaris
resource_id="55c1c993-1124-47f9-b823-514ba3849a9a"

curl -X POST "https://api.alcf.anl.gov/api/v2/compute/status/${resource_id}?historical=false&limit=10&offset=0" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Polaris
resource_id = "55c1c993-1124-47f9-b823-514ba3849a9a"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/compute/status/{resource_id}",
    params={
        "historical": "false",
        "limit": 10,
        "offset": 0
    },
    headers=headers
)

print(response.status_code)
print(response.json())

You can filter results by adding a JSON body (e.g., {"states": ["active"]}) to the request:

# Filter by job state
curl -X POST "https://api.alcf.anl.gov/api/v2/compute/status/${resource_id}?historical=true&limit=10&offset=0" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"states": ["active"]}'
# Filter by job state
response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/compute/status/{resource_id}",
    params={"historical": "true", "limit": 10, "offset": 0},
    json={"states": ["active"]},
    headers=headers
)

Available filters are:

  • states: List of job states (new, queued, held, active, completed, failed, canceled)
    • Example: {"states": ["active", "completed"]}
  • owner: ALCF username
    • Example: {"owner": "<username>"}
  • jobIds: List of job IDs
    • Example: {"jobIds": ["12345", "12346", "12347"]}
  • queue: Name of the PBS queue
    • Example: {"queue": "debug"}
  • accountingId: Name of the compute allocation
    • Example: {"accountingId": "<project>"}

Combining Filters

More than one filter can be added to the same request body:

  • Example: {"states": ["active"], "queue": "debug"}
2.3. Get a Specific Job

Returns the status and details of a single job by its ID.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Polaris
resource_id="55c1c993-1124-47f9-b823-514ba3849a9a"
job_id="<jobid>"

curl -X GET "https://api.alcf.anl.gov/api/v2/compute/status/${resource_id}/${job_id}?historical=true" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Polaris
resource_id = "55c1c993-1124-47f9-b823-514ba3849a9a"
job_id = "<jobid>"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v2/compute/status/{resource_id}/{job_id}",
    params={"historical": "true"},
    headers=headers
)

print(response.status_code)
print(response.json())
2.4. Cancel a Job

Cancels a queued or running job. Returns HTTP 204 No Content on success.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Polaris
resource_id="55c1c993-1124-47f9-b823-514ba3849a9a"
job_id="<jobid>"

curl -X DELETE "https://api.alcf.anl.gov/api/v2/compute/cancel/${resource_id}/${job_id}" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Polaris
resource_id = "55c1c993-1124-47f9-b823-514ba3849a9a"
job_id = "<jobid>"

response = requests.delete(
    f"https://api.alcf.anl.gov/api/v2/compute/cancel/{resource_id}/{job_id}",
    headers=headers
)

print(response.status_code)
print("Job canceled." if response.status_code == 204 else response.json())

3. Filesystem

Changes from API v1

All filesystem operations in API v2 are POST requests with a JSON body. In v1, most of them used GET, PUT, or DELETE; expand API v1 in an example to see its v1 request.

Asynchronous Operations

All filesystem operations are asynchronous and return a task ID. See Get a Task for how to retrieve your results.

Currently Supported Filesystems

  • Flare (All paths must start with /flare or /lus/flare/projects)
  • Eagle (All paths must start with /eagle or /lus/eagle)
  • Home (All paths must start with /home)
  • Grand (Please target Eagle with /lus/eagle/clone/g2/projects/)
3.1. List Directory Contents (ls)

Returns the contents of a directory on the specified resource.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/ls/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>"}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X GET "https://api.alcf.anl.gov/api/v1/filesystem/ls/${resource_id}?path=/eagle/<project>" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/ls/{resource_id}",
    json={"path": "/eagle/<project>"},
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v1/filesystem/ls/{resource_id}",
    params={"path": "/eagle/<project>"},
    headers=headers
)

print(response.status_code)
print(response.json())
3.2. Create a Directory (mkdir)

Creates a new directory at the specified path. Set parent to True to create any missing parent directories.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/mkdir/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/my_new_dir", "parent": false}'
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/mkdir/{resource_id}",
    json={
        "path": "/eagle/<project>/my_new_dir",
        "parent": False
    },
    headers=headers
)

print(response.status_code)
print(response.json())
3.3. View File Contents (view)

Returns a portion of a file starting at a given byte offset and reading up to size bytes.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/view/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "size": 10, "offset": 0}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X GET "https://api.alcf.anl.gov/api/v1/filesystem/view/${resource_id}?path=/eagle/<project>/file.txt&size=10&offset=0" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/view/{resource_id}",
    json={
        "path": "/eagle/<project>/file.txt",
        "size": 10,
        "offset": 0
    },
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v1/filesystem/view/{resource_id}",
    params={"path": "/eagle/<project>/file.txt", "size": 10, "offset": 0},
    headers=headers
)

print(response.status_code)
print(response.json())
3.4. Read First Lines of a File (head)

Returns the first N lines of a file.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/head/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "lines": 3}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X GET "https://api.alcf.anl.gov/api/v1/filesystem/head/${resource_id}?path=/eagle/<project>/file.txt&lines=3" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/head/{resource_id}",
    json={
        "path": "/eagle/<project>/file.txt",
        "lines": 3
    },
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v1/filesystem/head/{resource_id}",
    params={"path": "/eagle/<project>/file.txt", "lines": 3},
    headers=headers
)

print(response.status_code)
print(response.json())
3.5. Read Last Lines of a File (tail)

Returns the last N lines of a file.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/tail/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "lines": 3}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X GET "https://api.alcf.anl.gov/api/v1/filesystem/tail/${resource_id}?path=/eagle/<project>/file.txt&lines=3" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/tail/{resource_id}",
    json={
        "path": "/eagle/<project>/file.txt",
        "lines": 3
    },
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v1/filesystem/tail/{resource_id}",
    params={"path": "/eagle/<project>/file.txt", "lines": 3},
    headers=headers
)

print(response.status_code)
print(response.json())
3.6. Get File Checksum (checksum)

Returns the SHA-256 checksum of a file.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/checksum/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt"}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X GET "https://api.alcf.anl.gov/api/v1/filesystem/checksum/${resource_id}?path=/eagle/<project>/file.txt" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/checksum/{resource_id}",
    json={"path": "/eagle/<project>/file.txt"},
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v1/filesystem/checksum/{resource_id}",
    params={"path": "/eagle/<project>/file.txt"},
    headers=headers
)

print(response.status_code)
print(response.json())
3.7. Get File Type (file)

Returns the type of a file or directory.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/file/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt"}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X GET "https://api.alcf.anl.gov/api/v1/filesystem/file/${resource_id}?path=/eagle/<project>/file.txt" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/file/{resource_id}",
    json={"path": "/eagle/<project>/file.txt"},
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v1/filesystem/file/{resource_id}",
    params={"path": "/eagle/<project>/file.txt"},
    headers=headers
)

print(response.status_code)
print(response.json())
3.8. Change File Ownership (chown)

Changes the owner and/or group of a file or directory.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/chown/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "owner": "<username>", "group": "<group>"}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X PUT "https://api.alcf.anl.gov/api/v1/filesystem/chown/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "owner": "<username>", "group": "<group>"}'
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/chown/{resource_id}",
    json={
        "path": "/eagle/<project>/file.txt",
        "owner": "<username>",
        "group": "<group>"
    },
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.put(
    f"https://api.alcf.anl.gov/api/v1/filesystem/chown/{resource_id}",
    json={"path": "/eagle/<project>/file.txt", "owner": "<username>", "group": "<group>"},
    headers=headers
)

print(response.status_code)
print(response.json())
3.9. Change File Permissions (chmod)

Changes the permissions of a file or directory using an octal mode string.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/chmod/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "mode": "700"}'
API v1
access_token=$(alcf-tokens get-token iri)

# Eagle
resource_id="1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

curl -X PUT "https://api.alcf.anl.gov/api/v1/filesystem/chmod/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/eagle/<project>/file.txt", "mode": "700"}'
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Eagle
resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/chmod/{resource_id}",
    json={
        "path": "/eagle/<project>/file.txt",
        "mode": "700"
    },
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "1c3ad9d4-2e91-42bc-becb-72b1fde1235c"

response = requests.put(
    f"https://api.alcf.anl.gov/api/v1/filesystem/chmod/{resource_id}",
    json={"path": "/eagle/<project>/file.txt", "mode": "700"},
    headers=headers
)

print(response.status_code)
print(response.json())
3.10. Remove File or Directory (rm)

Delete file or directory given a specific path.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

# Home
resource_id="6115bd2c-957a-4543-abff-5fae52992ff2"

curl -X POST "https://api.alcf.anl.gov/api/v2/filesystem/rm/${resource_id}" \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     -d '{"path": "/home/<username>/my_dir"}'
API v1
access_token=$(alcf-tokens get-token iri)

# Home
resource_id="6115bd2c-957a-4543-abff-5fae52992ff2"

curl -X DELETE "https://api.alcf.anl.gov/api/v1/filesystem/rm/${resource_id}?path=/home/<username>/my_dir" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

# Home
resource_id = "6115bd2c-957a-4543-abff-5fae52992ff2"

response = requests.post(
    f"https://api.alcf.anl.gov/api/v2/filesystem/rm/{resource_id}",
    json={"path": "/home/<username>/my_dir"},
    headers=headers
)

print(response.status_code)
print(response.json())
API v1
import requests
from alcf_tokens.auth import get_access_token

access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

resource_id = "6115bd2c-957a-4543-abff-5fae52992ff2"

response = requests.delete(
    f"https://api.alcf.anl.gov/api/v1/filesystem/rm/{resource_id}",
    params={"path": "/home/<username>/my_dir"},
    headers=headers
)

print(response.status_code)
print(response.json())

4. Tasks

4.1. Get a Task

Retrieves the status and result of an asynchronous task by its ID.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

task_id="<task_id>"

curl -X GET "https://api.alcf.anl.gov/api/v2/task/${task_id}" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

task_id = "<task_id>"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v2/task/{task_id}",
    headers=headers
)

print(response.status_code)
print(response.json())

5. Account

5.1. List Projects

Returns the list of projects associated with your account.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

curl -X GET "https://api.alcf.anl.gov/api/v2/account/projects" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.alcf.anl.gov/api/v2/account/projects",
    headers=headers
)

print(response.status_code)
print(response.json())
5.2. Get a Specific Project

Returns a specific project by its ID.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

project_id="<project_id>"

curl -X GET "https://api.alcf.anl.gov/api/v2/account/projects/${project_id}" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

project_id = "<project_id>"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v2/account/projects/{project_id}",
    headers=headers
)

print(response.status_code)
print(response.json())
5.3. List Project Allocations

Returns the list of allocations for a specific project.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

project_id="<project_id>"

curl -X GET "https://api.alcf.anl.gov/api/v2/account/projects/${project_id}/project_allocations" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

project_id = "<project_id>"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v2/account/projects/{project_id}/project_allocations",
    headers=headers
)

print(response.status_code)
print(response.json())
5.4. Get a Specific Project Allocation

Returns a specific project allocation by its ID.

#!/bin/bash
access_token=$(alcf-tokens get-token iri)

project_id="<project_id>"
project_allocation_id="<allocation_id>"

curl -X GET "https://api.alcf.anl.gov/api/v2/account/projects/${project_id}/project_allocations/${project_allocation_id}" \
     -H "Authorization: Bearer ${access_token}"
import requests
from alcf_tokens.auth import get_access_token

# Create headers with access token
access_token = get_access_token("iri")
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

project_id = "<project_id>"
project_allocation_id = "<allocation_id>"

response = requests.get(
    f"https://api.alcf.anl.gov/api/v2/account/projects/{project_id}/project_allocations/{project_allocation_id}",
    headers=headers
)

print(response.status_code)
print(response.json())

Troubleshooting

  • Permission Denied: Your token may have expired or you may not be authenticated with your ALCF credentials. Logout from Globus at app.globus.org/logout, clear your browser cache or use an incognito window, and re-authenticate.
  • IdentityMismatchError: Detected a change in identity: This happens when trying to get an access token using a Globus identity that is not linked to the one you previously used. Locate your tokens file (typically at ~/.globus/app/7f3e61f5-e0de-4e8f-9150-0a62c65dda63/alcf_tokens/tokens.json or ~/.globus/app/8b84fc2d-49e9-49ea-b54d-b3a29a70cf31/alcf_facility_api_app/tokens.json), delete it, and restart the authentication process.

Further Information

Further information on and examples for the IRI API may be found at https://github.com/doe-iri

Contact Us

For questions or support, please contact ALCF Support.