# AgentRun (/api/reference/objects/agent-run)

One piece of work an agent did, or is doing. A sourcing run also keeps a timeline of what happened and the full log of the process.

```graphql
type AgentRun {
  agent: Agent!
  completedAt: DateTime
  createdAt: DateTime!
  error: String
  events(
    after: String
    before: String
    first: Int
    last: Int
  ): AgentRunEventConnection!
  id: ID!
  logFiles: [AgentRunLogFile!]!
  outcome: AgentRunOutcome!
  sourcedCandidateCount: Int
  sourcingMethod: SourcingMethod
  startedAt: DateTime
  status: AgentRunStatus!
  trigger: String!
}
```

### Fields [#fields]

#### [`AgentRun.agent`](#agent) · [`Agent!`](/api/reference/objects/agent) `non-null` `object` [#agent]
The agent that ran.

#### [`AgentRun.completedAt`](#completed-at) · [`DateTime`](/api/reference/scalars/date-time) `scalar` [#completed-at]
When the run finished or failed. Null until then.

#### [`AgentRun.createdAt`](#created-at) · [`DateTime!`](/api/reference/scalars/date-time) `non-null` `scalar` [#created-at]
When the run was created. It may wait before it starts.

#### [`AgentRun.error`](#error) · [`String`](/api/reference/scalars/string) `scalar` [#error]
Why the run failed, as recorded. Null unless `status` is `FAILED`.

#### [`AgentRun.events`](#events) · [`AgentRunEventConnection!`](/api/reference/objects/agent-run-event-connection) `non-null` `object` [#events]
What happened during the run, oldest first. While the run is going, pass the last cursor you hold as `after` to read only what is new. Only sourcing runs record events.
##### [`AgentRun.events.after`](#agent-run-events-after) · [`String`](/api/reference/scalars/string) `scalar` [#agent-run-events-after]
Return the rows that follow this cursor.

##### [`AgentRun.events.before`](#agent-run-events-before) · [`String`](/api/reference/scalars/string) `scalar` [#agent-run-events-before]
Return the rows that come before this cursor.

##### [`AgentRun.events.first`](#agent-run-events-first) · [`Int`](/api/reference/scalars/int) `scalar` [#agent-run-events-first]
How many rows to return, from the start or from `after`. 50 when left out, 200 at most.

##### [`AgentRun.events.last`](#agent-run-events-last) · [`Int`](/api/reference/scalars/int) `scalar` [#agent-run-events-last]
How many rows to return, counting back from the end or from `before`. 200 at most.

#### [`AgentRun.id`](#id) · [`ID!`](/api/reference/scalars/id) `non-null` `scalar` [#id]
The run's id.

#### [`AgentRun.logFiles`](#log-files) · [`[AgentRunLogFile!]!`](/api/reference/objects/agent-run-log-file) `non-null` `object` [#log-files]
The full, redacted log of the process, newest first: the latest 20 files. Empty until the run finishes or fails, when log storage was unavailable, and for a run that is not a sourcing run, whose files the download routes refuse.

#### [`AgentRun.outcome`](#outcome) · [`AgentRunOutcome!`](/api/reference/enums/agent-run-outcome) `non-null` `enum` [#outcome]
What the run came to, in one word. For a sourcing run this separates finding nobody from finding people.

#### [`AgentRun.sourcedCandidateCount`](#sourced-candidate-count) · [`Int`](/api/reference/scalars/int) `scalar` [#sourced-candidate-count]
How many candidates a sourcing run added. Null for other runs, and until the run has finished.

#### [`AgentRun.sourcingMethod`](#sourcing-method) · [`SourcingMethod`](/api/reference/enums/sourcing-method) `enum` [#sourcing-method]
Which way of sourcing the run used. Null when the run is not a sourcing run.

#### [`AgentRun.startedAt`](#started-at) · [`DateTime`](/api/reference/scalars/date-time) `scalar` [#started-at]
When work began. Null while the run is waiting.

#### [`AgentRun.status`](#status) · [`AgentRunStatus!`](/api/reference/enums/agent-run-status) `non-null` `enum` [#status]
How far the run has got. Poll while it is `PENDING` or `RUNNING`.

#### [`AgentRun.trigger`](#trigger) · [`String!`](/api/reference/scalars/string) `non-null` `scalar` [#trigger]
What started it: `manual` when a person asked, `scheduled`, `event:` and the event's name (such as `event:candidate.created`), or `sourcing:` or `context:` and the task for a sourcing run.

### Returned By [#returned-by]

[`agentRun`](/api/reference/queries/agent-run)  `query`

### Member Of [#member-of]

[`AgentRunEdge`](/api/reference/objects/agent-run-edge)  `object` · [`RunAgentPayload`](/api/reference/objects/run-agent-payload)  `object`