Scheduled Investigations

Scheduled investigations let you automate recurring security checks. Define a query once, set a frequency, and SoCMate runs the investigation automatically on schedule, notifying you when findings are detected.

Use Cases

Daily sign-in monitoring — Check for brute force patterns every morning
Weekly threat hunting — Search for lateral movement indicators across your environment
Monthly compliance checks — Verify security baselines and audit log completeness
One-time delayed investigation — Schedule an investigation to run at a specific future time

Creating a Schedule

From the UI

Navigate to Schedules in the sidebar and click Create Schedule. Fill in the investigation query, persona, frequency, and preferred run time.

From the API

Validate the query

Before creating a schedule, validate that your query is specific enough for recurring execution:

curl -X POST https://api.socmate.yourcompany.com/api/v1/schedules/validate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Check for failed sign-ins in the last 24 hours with more than 5 attempts from the same IP",
    "persona": "soc_analyst"
  }'

The validation checks that the query has enough specificity (concrete entities, clear time scoping, measurable conditions) for consistent recurring execution.

Create the schedule

curl -X POST https://api.socmate.yourcompany.com/api/v1/schedules \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily failed sign-in check",
    "description": "Check for brute force patterns across all user accounts",
    "user_query": "Check for failed sign-ins in the last 24 hours with more than 5 attempts from the same IP",
    "persona": "soc_analyst",
    "frequency": "daily",
    "scheduled_time": "08:00"
  }'

Frequency Options

Frequency	Description	Example
`once`	Runs a single time at the scheduled time	One-time overnight scan
`daily`	Runs every day at the scheduled time	Morning sign-in review
`weekly`	Runs once per week	Weekly threat hunt
`monthly`	Runs once per month	Monthly compliance check
`custom`	Raw cron expression for advanced scheduling	`0 /6 * *` (every 6 hours)

For once schedules, the status automatically changes to COMPLETED after the single run finishes. All other frequencies continue running until manually paused or deleted.

Schedule Lifecycle

ACTIVE ──── (runs on schedule) ──── ACTIVE
   │                                   │
   │ Manual pause                      │ 5 consecutive failures
   ▼                                   ▼
PAUSED                              FAILED
   │
   │ Resume
   ▼
ACTIVE

ONCE frequency:
ACTIVE ──── (single run) ──── COMPLETED

Managing Schedules

List Schedules

curl -X GET "https://api.socmate.yourcompany.com/api/v1/schedules?status=active" \
  -H "Authorization: Bearer <token>"

Update a Schedule

Modify the query, frequency, or scheduled time. The next run time is automatically recalculated.

curl -X PATCH https://api.socmate.yourcompany.com/api/v1/schedules/{schedule_id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": "weekly",
    "scheduled_time": "06:00"
  }'

Trigger an Immediate Run

Run a scheduled investigation immediately without waiting for the next scheduled time:

curl -X POST https://api.socmate.yourcompany.com/api/v1/schedules/{schedule_id}/run \
  -H "Authorization: Bearer <token>"

Response:

{
  "session_id": "sess_abc123"
}

The ad-hoc run does not affect the regular schedule timing.

Delete a Schedule

Soft-deletes the schedule. It will no longer run.

curl -X DELETE https://api.socmate.yourcompany.com/api/v1/schedules/{schedule_id} \
  -H "Authorization: Bearer <token>"

Monitoring Runs

View Run History

See the last 50 runs for a schedule, including status, duration, and linked investigation sessions:

curl -X GET https://api.socmate.yourcompany.com/api/v1/schedules/{schedule_id}/runs \
  -H "Authorization: Bearer <token>"

Run Statuses

Status	Description
`running`	Investigation is currently in progress
`completed`	Investigation finished successfully
`failed`	Investigation encountered an error

If a scheduled investigation remains in running state for more than 1 hour, it is automatically marked as failed. This prevents stuck runs from blocking future executions.

How It Works

Scheduled investigations run as automated background tasks:

Checking — SoCMate checks every minute for schedules past their next_run_at time
Triggering — For each due schedule, a new investigation session is started automatically
Monitoring — Run statuses are checked every 5 minutes for completed or failed runs
Notifications — Completion and failure notifications are sent through the notification system
Next run — After each run, the next_run_at is recalculated based on the frequency

Notifications

Scheduled investigations generate notifications on:

Completion — Investigation finished with results
Failure — Investigation encountered an error

Configure notification delivery (in-app, email) in your user settings.

Failure Handling

Individual run failures are recorded in the run history with error details
After 5 consecutive failures, the schedule is automatically disabled with status=FAILED
Failed schedules can be re-enabled after resolving the underlying issue
Common failure causes: Sentinel connectivity issues, query timeout, LLM provider errors

​Use Cases

​Creating a Schedule

​From the UI

​From the API

​Frequency Options

​Schedule Lifecycle

​Managing Schedules

​List Schedules

​Update a Schedule

​Trigger an Immediate Run

​Delete a Schedule

​Monitoring Runs

​View Run History

​Run Statuses

​How It Works

​Notifications

​Failure Handling

Use Cases

Creating a Schedule

From the UI

From the API

Frequency Options

Schedule Lifecycle

Managing Schedules

List Schedules

Update a Schedule

Trigger an Immediate Run

Delete a Schedule

Monitoring Runs

View Run History

Run Statuses

How It Works

Notifications

Failure Handling