Serverless Execution

Search Files (grep)

Searches files under a directory on the disk for lines matching a regular expression. Listing and matching are fanned out across ephemeral exec containers, so the request finishes within the user’s time budget regardless of the size of the directory.

The user controls cost and latency with three knobs:

maxDurationSeconds is the wall-clock deadline (capped at 30s).
concurrency is the maximum number of parallel grep workers. Higher concurrency finishes larger datasets within the deadline, at proportionally more compute.
maxResults causes the search to short-circuit after the aggregator has collected this many matches.

With recursive: false only files directly under directory are searched. With recursive: true subdirectories are walked breadth-first and grep workers are dispatched as soon as each level finishes listing — listing and matching overlap.

The matches returned when stopping early on maxResults are a sample of whichever workers reported first, not the lexicographically first N. The response surfaces stoppedReason so callers can distinguish completion from early termination.

POST

api

disks

{id}

grep

Parallel grep over a directory on a disk

curl --request POST \
  --url https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "directory": "data/logs",
  "pattern": "ERROR|FATAL",
  "recursive": false,
  "maxDurationSeconds": 30,
  "concurrency": 50,
  "maxResults": 1000
}
'

import requests

url = "https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep"

payload = {
    "directory": "data/logs",
    "pattern": "ERROR|FATAL",
    "recursive": False,
    "maxDurationSeconds": 30,
    "concurrency": 50,
    "maxResults": 1000
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    directory: 'data/logs',
    pattern: 'ERROR|FATAL',
    recursive: false,
    maxDurationSeconds: 30,
    concurrency: 50,
    maxResults: 1000
  })
};

fetch('https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'directory' => 'data/logs',
    'pattern' => 'ERROR|FATAL',
    'recursive' => false,
    'maxDurationSeconds' => 30,
    'concurrency' => 50,
    'maxResults' => 1000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep"

	payload := strings.NewReader("{\n  \"directory\": \"data/logs\",\n  \"pattern\": \"ERROR|FATAL\",\n  \"recursive\": false,\n  \"maxDurationSeconds\": 30,\n  \"concurrency\": 50,\n  \"maxResults\": 1000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"directory\": \"data/logs\",\n  \"pattern\": \"ERROR|FATAL\",\n  \"recursive\": false,\n  \"maxDurationSeconds\": 30,\n  \"concurrency\": 50,\n  \"maxResults\": 1000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"directory\": \"data/logs\",\n  \"pattern\": \"ERROR|FATAL\",\n  \"recursive\": false,\n  \"maxDurationSeconds\": 30,\n  \"concurrency\": 50,\n  \"maxResults\": 1000\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "matches": [
      {
        "file": "data/logs/2026-05-03.log",
        "line": 142,
        "text": "<string>"
      }
    ],
    "filesScanned": 123,
    "containersDispatched": 123,
    "computeSecondsUsed": 123,
    "durationMs": 123,
    "listingMs": 123,
    "grepMs": 123
  }
}

{
  "success": false,
  "error": "Invalid request parameters"
}

{
  "success": false,
  "error": "Invalid request parameters"
}

{
  "success": false,
  "error": "Invalid request parameters"
}

{
  "success": false,
  "error": "Invalid request parameters"
}

Authorizations

Authorization

string

header

required

API key

Path Parameters

string

required

Disk ID (format dsk-{16 hex chars})

Pattern: ^dsk-[0-9a-f]{16}$

Example:

"dsk-0123456789abcdef"

Body

application/json

Response

Grep completed (possibly stopped early)

success

boolean

required

Example:

true

data

object

required

Show child attributes

Execute Command with Multiple Disks

Add Disk User

⌘I

Parallel grep over a directory on a disk

curl --request POST \
  --url https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "directory": "data/logs",
  "pattern": "ERROR|FATAL",
  "recursive": false,
  "maxDurationSeconds": 30,
  "concurrency": 50,
  "maxResults": 1000
}
'

import requests

url = "https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep"

payload = {
    "directory": "data/logs",
    "pattern": "ERROR|FATAL",
    "recursive": False,
    "maxDurationSeconds": 30,
    "concurrency": 50,
    "maxResults": 1000
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    directory: 'data/logs',
    pattern: 'ERROR|FATAL',
    recursive: false,
    maxDurationSeconds: 30,
    concurrency: 50,
    maxResults: 1000
  })
};

fetch('https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'directory' => 'data/logs',
    'pattern' => 'ERROR|FATAL',
    'recursive' => false,
    'maxDurationSeconds' => 30,
    'concurrency' => 50,
    'maxResults' => 1000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep"

	payload := strings.NewReader("{\n  \"directory\": \"data/logs\",\n  \"pattern\": \"ERROR|FATAL\",\n  \"recursive\": false,\n  \"maxDurationSeconds\": 30,\n  \"concurrency\": 50,\n  \"maxResults\": 1000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"directory\": \"data/logs\",\n  \"pattern\": \"ERROR|FATAL\",\n  \"recursive\": false,\n  \"maxDurationSeconds\": 30,\n  \"concurrency\": 50,\n  \"maxResults\": 1000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://control.green.us-east-1.aws.prod.archil.com/api/disks/{id}/grep")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"directory\": \"data/logs\",\n  \"pattern\": \"ERROR|FATAL\",\n  \"recursive\": false,\n  \"maxDurationSeconds\": 30,\n  \"concurrency\": 50,\n  \"maxResults\": 1000\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "matches": [
      {
        "file": "data/logs/2026-05-03.log",
        "line": 142,
        "text": "<string>"
      }
    ],
    "filesScanned": 123,
    "containersDispatched": 123,
    "computeSecondsUsed": 123,
    "durationMs": 123,
    "listingMs": 123,
    "grepMs": 123
  }
}

{
  "success": false,
  "error": "Invalid request parameters"
}

{
  "success": false,
  "error": "Invalid request parameters"
}

{
  "success": false,
  "error": "Invalid request parameters"
}

{
  "success": false,
  "error": "Invalid request parameters"
}

Overview

Disks

Serverless Execution

Disk Users

API Tokens

Search Files (grep)

Authorizations

Path Parameters

Body

Response