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

1

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.
2

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

FrequencyDescriptionExample
onceRuns a single time at the scheduled timeOne-time overnight scan
dailyRuns every day at the scheduled timeMorning sign-in review
weeklyRuns once per weekWeekly threat hunt
monthlyRuns once per monthMonthly compliance check
customRaw cron expression for advanced scheduling0 */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

StatusDescription
runningInvestigation is currently in progress
completedInvestigation finished successfully
failedInvestigation 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:
  1. Checking — SoCMate checks every minute for schedules past their next_run_at time
  2. Triggering — For each due schedule, a new investigation session is started automatically
  3. Monitoring — Run statuses are checked every 5 minutes for completed or failed runs
  4. Notifications — Completion and failure notifications are sent through the notification system
  5. 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