> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealmanac.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploads and jobs

> Understand the write request, durable source change, and observable work it starts.

An upload and a job are related, but they are not the same thing.

<div className="almanac-diagram" tabIndex="0">
  <img src="https://mintcdn.com/almanac-e141534d/PSPQxvCsHo2cfSd-/images/diagrams/upload-job.svg?fit=max&auto=format&n=PSPQxvCsHo2cfSd-&q=85&s=5ee4307aeec1ad25603c6183eae9dcee" alt="New files change the source library and create one ingest job; duplicates alone create no job." width="1440" height="520" data-path="images/diagrams/upload-job.svg" />
</div>

## Upload

An upload receives one or more source files plus optional guidance. The source
library records files that are genuinely new.

## Ingest job

If at least one source is new, Almanac creates one ingest job. Jobs move through:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
queued → running → succeeded
                 ↘ failed
```

Events explain progress. The final job and outcome explain what sources and pages
changed.

## Duplicate-only upload

When every file already exists, the upload succeeds with no new job. This is why
programs must treat the upload's `job` field as nullable and why `last` is unsafe
for concurrent automation.

Apply the model in [Upload sources](/guides/upload-sources), [Follow a job](/guides/follow-job),
or [upload with Python](/sdk/sources-and-jobs).