> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Search automation runs > Paginated run log for one automation. Does not include per-action steps; use `GET /v1/automations/runs/{runId}` for steps. Only organization admins, API keys and the automation's creator can see its runs. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/automations/{id}/runs/search openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/automations/{id}/runs/search: post: tags: - Automations summary: Search automation runs description: >- Paginated run log for one automation. Does not include per-action steps; use `GET /v1/automations/runs/{runId}` for steps. Only organization admins, API keys and the automation's creator can see its runs. operationId: searchAutomationRuns parameters: - in: path name: id required: true schema: type: string description: Automation ID requestBody: content: application/json: schema: $ref: '#/components/schemas/AutomationRunsSearchBody' responses: '200': description: Runs found content: application/json: schema: $ref: '#/components/schemas/AutomationRunsSearchResponse' example: success: true data: - id: bbb22222-cccc-dddd-eeee-ffffffffffff0001 automation_id: aaa11111-bbbb-cccc-dddd-eeeeeeee2222 status: waiting attempts: 0 error_message: null trigger_type: candidate_status_changed trigger_payload: candidate_id: 345e6789-e01b-23c4-d567-890123456789 person_id: 456e7890-e12b-34d5-a678-901234567890 job_id: 456e7890-e12b-34d5-a678-901234567890 old_pipeline_stage_id: 123e4567-e89b-12d3-a456-426614174000 new_pipeline_stage_id: 123e4567-e89b-12d3-a456-426614174000 old_job_status_id: 234e5678-e90a-12b3-c456-789012345678 new_job_status_id: 234e5678-e90a-12b3-c456-789012345678 old_deal_status_id: 7a2e3d4c-5b6f-4071-8b8c-9d0e1f2a3b4c new_deal_status_id: 7a2e3d4c-5b6f-4071-8b8c-9d0e1f2a3b4c job_status_id: 234e5678-e90a-12b3-c456-789012345678 organization_company_id: 678e9012-e34d-56e7-f890-123456789012 scheduled_for: '2026-08-21T10:05:00Z' change_source: api candidate_id: 345e6789-e01b-23c4-d567-890123456789 person_id: 456e7890-e12b-34d5-a678-901234567890 job_id: 456e7890-e12b-34d5-a678-901234567890 deal_id: 6f1d2c3b-4a5e-4f60-9a7b-8c9d0e1f2a3b started_at: '2026-08-21T10:05:00Z' finished_at: null resume_at: '2026-08-23T10:05:01Z' created_at: '2026-08-21T10:05:00Z' updated_at: '2026-08-21T10:05:01Z' meta: total: 4 offset: 0 limit: 100 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '403': description: Only admins and the automation's creator can see its runs content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: AutomationRunsSearchBody: type: object properties: offset: type: - integer - 'null' minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. limit: type: integer minimum: 1 maximum: 100 default: 100 description: Max records per page (1–100). Defaults to 100. statuses: type: array items: type: string enum: - pending - processing - waiting - completed - failed - skipped - dead_letter description: Filter by one or more run statuses. trigger_type: type: string enum: - schedule - candidate_status_changed - job_status_changed - job_created - deal_status_changed description: Filter by the trigger that created the run. person_id: type: string format: uuid description: Filter to runs for one candidate (person). sort_by: type: string enum: - created_at - started_at - finished_at default: created_at description: Column to sort by. Defaults to created_at. sort_order: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to desc. AutomationRunsSearchResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/AutomationRun' meta: type: object properties: total: type: number description: Total matching records across all pages. offset: type: number description: Current pagination offset. limit: type: number description: Page size used for this request. required: - total - offset - limit required: - success - data - meta AutomationRun: type: object properties: id: type: string format: uuid description: Run UUID. automation_id: type: string format: uuid status: type: string enum: - pending - processing - waiting - completed - failed - skipped - dead_letter description: >- `waiting` means the run is paused on a delay action until `resume_at`. `completed` means at least one action did work. `skipped` means the run finished without any action doing work, for example when the automation has no actions or every action was skipped, or it was turned off while waiting. `failed` will be retried; `dead_letter` will not. attempts: type: integer error_message: type: - string - 'null' trigger_type: type: string enum: - schedule - candidate_status_changed - job_status_changed - job_created - deal_status_changed trigger_payload: type: - object - 'null' properties: candidate_id: type: string format: uuid person_id: type: string format: uuid job_id: type: string format: uuid old_pipeline_stage_id: type: - string - 'null' format: uuid new_pipeline_stage_id: type: - string - 'null' format: uuid old_job_status_id: type: - string - 'null' format: uuid new_job_status_id: type: - string - 'null' format: uuid old_deal_status_id: type: - string - 'null' format: uuid new_deal_status_id: type: - string - 'null' format: uuid job_status_id: type: - string - 'null' format: uuid description: >- For a "new search created" trigger, the status the record was created with. organization_company_id: type: - string - 'null' format: uuid description: >- For a "new search created" trigger, the client the record was created for. Null when it has no client. scheduled_for: type: string change_source: type: - string - 'null' enum: - api - mcp description: >- api or mcp when the change that started this run was made through the API or MCP (including Zapier). Null for changes made in Stardex and for scheduled runs. candidate_id: type: - string - 'null' format: uuid person_id: type: - string - 'null' format: uuid job_id: type: - string - 'null' format: uuid deal_id: type: - string - 'null' format: uuid description: The deal a deal status trigger fired for. Null for other triggers. started_at: type: - string - 'null' finished_at: type: - string - 'null' resume_at: type: - string - 'null' description: When a waiting run continues. Null unless status is waiting. created_at: type: string updated_at: type: string steps: type: array items: $ref: '#/components/schemas/AutomationRunStep' required: - id - automation_id - status - attempts - error_message - trigger_type - trigger_payload - change_source - candidate_id - person_id - job_id - deal_id - started_at - finished_at - resume_at - created_at - updated_at AutomationRunStep: type: object properties: id: type: string format: uuid description: Step UUID. position: type: integer description: 1-based action order. action_id: type: - string - 'null' format: uuid description: Source action UUID at enqueue time, if still present. action_type: type: string enum: - send_email - add_note - agent_instructions - delay - create_task action_config: type: object properties: action_id: type: string format: uuid position: type: integer action_type: type: string enum: - send_email - add_note - agent_instructions - delay - create_task recipient_type: type: - string - 'null' enum: - candidate - team_member - team_members - job_owner - deal_owner - client_contacts team_member_id: type: - string - 'null' format: uuid payload: anyOf: - type: object properties: subject: type: string minLength: 1 description: >- Email subject line. Supports the same {{variables}} as the body. body: type: string minLength: 1 description: >- Plain text email body. Blank lines start a new paragraph. Supports {{candidate_name}}, {{candidate_first_name}}, {{job_name}}, {{stage_name}}, {{job_status_name}}, {{client_name}}, {{deal_name}}, {{deal_status_name}} and {{search_owner}} where the trigger provides them. sender: oneOf: - type: object properties: kind: type: string enum: - mailbox nylas_grant_id: type: string format: uuid description: >- A connected mailbox the automation's owner owns or has shared access to. required: - kind - nylas_grant_id - type: object properties: kind: type: string enum: - job_owner description: >- Send from the job owner's mailbox. The automation's owner must have access to it when the email is sent. required: - kind description: >- Which mailbox sends the email. Required when recipient_type is candidate or client_contacts. Emails to team members come from Stardex instead. team_member_ids: type: array items: type: string format: uuid maxItems: 50 description: >- Teammates who receive the email when recipient_type is team_members. Get IDs from GET /v1/team-members. email_addresses: type: array items: type: string format: email maxItems: 50 description: >- Other addresses that receive the email when recipient_type is team_members, for example finance@yourfirm.com. They get it from Stardex, like teammates do. include_signature: type: boolean description: >- Add the sending mailbox's signature to the end of the email. Only applies to candidate and client_contacts emails, which are sent from a mailbox. Defaults to false. required: - subject - body - type: object properties: content: type: string minLength: 1 description: >- Note text added to the candidate. Supports {{candidate_name}}, {{job_name}}, {{stage_name}}, and {{client_name}}. required: - content - type: object properties: instructions: type: string minLength: 1 description: >- Natural-language instructions for the agent. The agent is not executed yet; this is stored only. required: - instructions - type: object properties: amount: type: integer minimum: 1 description: >- How many units to wait before the next action. Whole number, at least 1. example: 2 unit: type: string enum: - minutes - hours - days description: Unit for amount. A day is a fixed 24 hours. example: days required: - amount - unit - type: object properties: content: type: string minLength: 1 description: >- Task text. Supports {{candidate_name}}, {{job_name}}, {{stage_name}}, {{job_status_name}} and {{client_name}} where the trigger provides them. task_type: type: string enum: - text - linkedin_message - linkedin_connection - call - other description: >- Task type, the same values as tasks elsewhere in Stardex. due_in_days: anyOf: - type: number enum: - 0 - type: number enum: - 1 - type: number enum: - 3 - type: number enum: - 7 description: >- Days after the step runs that the task is due. 0 means the same day. example: 1 required: - content - task_type - due_in_days required: - action_id - position - action_type - recipient_type - team_member_id - payload status: type: string enum: - pending - processing - waiting - completed - failed - skipped description: >- Outcome of this action. `waiting` means a delay action is paused until `result.resume_at`. `skipped` means the action did not do anything — check `result.code` for why. Action types that are not available yet report `not_implemented` there. attempt: type: integer error_message: type: - string - 'null' result: type: - object - 'null' properties: code: type: string message: type: string resume_at: type: string description: 'Delay actions only: ISO 8601 time the wait ends.' from_email: type: string description: >- Send email actions only: the mailbox an external email was sent from. deliveries: type: array items: type: object properties: to_email: type: string status: type: string enum: - sent - skipped - failed description: >- sent, skipped (a check stopped it, see reason), or failed (the send errored for this recipient; the others were still sent). reason: type: string description: Why the email to this recipient was not sent. required: - to_email - status description: 'Send email actions only: the outcome for each recipient.' due_at: type: string description: 'Create task actions only: ISO 8601 due date of the created task.' sender_retry_count: type: integer description: >- Send email actions only: how many times the step waited for a sending mailbox that could not send. started_at: type: - string - 'null' finished_at: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - position - action_id - action_type - action_config - status - attempt - error_message - result - started_at - finished_at - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.