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
}
'

{
  "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
  }
}

Authorizations

Authorization

string

header

required

API key (format key-{API_KEY})

Path Parameters

id

string

required

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

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

Example:

"dsk-0123456789abcdef"

Body

application/json

directory

string

required

Directory on the disk to search, relative to the disk root. An empty string or "/" means the disk root.

Example:

"data/logs"

pattern

string

required

Extended regular expression (passed to grep -E)

Example:

"ERROR|FATAL"

recursive

boolean

default:false

When true, walks subdirectories breadth-first.

maxDurationSeconds

integer

default:30

Wall-clock deadline for the entire request. Capped at 30 seconds because the runtime exec container itself is bounded at ~30s; longer requests would have their workers killed mid-scan.

Required range: 1 <= x <= 30

concurrency

integer

default:50

Maximum number of parallel grep workers. Higher values finish larger datasets within the deadline but consume proportionally more runtime capacity.

Required range: 1 <= x <= 100

maxResults

integer

default:1000

Stop scanning once the aggregator has this many matches. Returned matches are a sample of whichever workers reported first, not the lexicographically first N.

Required range: 1 <= x <= 10000

Response

Grep completed (possibly stopped early)

success

boolean

required

Example:

true

data

object

required

Show child attributes

Execute Command with Multiple Disks

⌘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
}
'

{
  "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
  }
}