# How to Customize the Audit Process in Open‑SEO: Configuration Options and Limits

> Customize the Open-SEO audit process with configuration options. Adjust maxPages for crawl depth and lighthouseStrategy for performance checks to tailor your SEO analysis.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-08-21

---

**You can customize the Open‑SEO audit process by adjusting two parameters in the `AuditConfig` object—`maxPages` to control crawl depth and `lighthouseStrategy` to toggle performance checks—while deeper crawling policies remain hard‑coded in the workflow modules.**

The open‑source SEO toolkit every-app/open-seo exposes a server‑side audit workflow that allows limited but precise customization through configuration objects. While the core crawling logic is encapsulated in workflow phases, operators can tailor individual audit runs by modifying specific fields in the `AuditConfig` record stored with each audit.

## Audit Configuration Options

Open‑SEO stores customizable parameters in the `AuditConfig` type defined in [`src/server/lib/audit/types.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/types.ts). When you invoke `AuditService.startAudit`, the function persists these values alongside the audit record, and downstream workflow phases read them to determine execution behavior.

### Page Count Limits (`maxPages`)

The `maxPages` property defines the upper bound of URLs the crawler will visit during an audit. According to the source code in [`src/server/features/audit/services/AuditService.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/audit/services/AuditService.ts), this value is clamped against the `AUDIT_LIMITS` constant based on the user's plan tier—free plans default to 50 pages, while paid or self‑hosted deployments can specify higher limits or unlimited crawling.

### Lighthouse Strategy (`lighthouseStrategy`)

The `lighthouseStrategy` field controls whether Google Lighthouse performance audits run against discovered pages. The enum accepts two values:

- `"auto"` – Executes Lighthouse on every page crawled
- `"none"` – Skips performance checks entirely

This setting is parsed in the workflow phases to conditionally launch the Lighthouse runner.

## How the Audit Configuration Works

The audit lifecycle follows a strict persistence pattern. In `AuditService.startAudit` (lines 46‑69), the function constructs the audit record and embeds the supplied configuration as JSON. Later, retrieval methods such as `getResults` invoke `parseAuditConfig` (lines 70‑85) to deserialize these settings, while [`siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/siteAuditWorkflowPhases.ts) consumes the configuration to decide when to terminate crawling or skip performance analysis (lines 170‑176).

Because the workflow is implemented as a TanStack Server Function, these stored parameters represent the only runtime customization points available through the public API.

## Starting an Audit with Custom Settings

To customize an audit, pass the configuration fields directly to the `startAudit` method:

```typescript
import { AuditService } from "@/server/features/audit/services/AuditService";

await AuditService.startAudit({
  actorUserId: "user-123",
  billingCustomer: {
    userId: "user-123",
    userEmail: "user@example.com",
    organizationId: "org-456",
    projectId: "proj-789",
  },
  projectId: "proj-789",
  startUrl: "https://example.com",
  // Customizations:
  maxPages: 200,
  lighthouseStrategy: "none",
  limitTier: "self_hosted",
});

```

The `maxPages: 200` value overrides the default crawl depth, while `lighthouseStrategy: "none"` disables performance audits. Note that `maxPages` remains subject to plan‑tier enforcement defined in `AUDIT_LIMITS`.

## Retrieving Applied Configuration

Existing audits expose their stored configuration through the results endpoint:

```typescript
import { AuditService } from "@/server/features/audit/services/AuditService";

const result = await AuditService.getResults("audit-uuid", "proj-789");
console.log(result.audit.config);
// Output: { maxPages: 200, lighthouseStrategy: "none" }

```

The `getResults` method uses `parseAuditConfig` to validate and return the JSON configuration persisted during audit creation.

## Hard‑Coded Behaviors You Cannot Change

Not all aspects of the audit are configurable. The workflow phases in [`src/server/workflows/siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/siteAuditWorkflowPhases.ts) hard‑code policies for:

- URL discovery algorithms
- [`robots.txt`](https://github.com/every-app/open-seo/blob/main/robots.txt) handling
- Link‑following depth logic
- Request throttling and concurrency

Modifying these behaviors requires editing the workflow source code directly rather than passing configuration parameters.

## Summary

- **Open‑SEO audits** are customized via the `AuditConfig` object stored with each audit record in [`src/server/lib/audit/types.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/types.ts).
- **Two configurable fields** exist: `maxPages` (crawl volume limit) and `lighthouseStrategy` (performance check toggle).
- **Plan‑tier enforcement** automatically clamps `maxPages` against `AUDIT_LIMITS` defined in [`AuditService.ts`](https://github.com/every-app/open-seo/blob/main/AuditService.ts).
- **Workflow internals** such as crawling logic and robots handling are hard‑coded in [`siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/siteAuditWorkflowPhases.ts) and cannot be altered via configuration.

## Frequently Asked Questions

### Can I change the crawling speed or concurrent requests in Open‑SEO?

No. Concurrency, request throttling, and retry policies are hard‑coded in the workflow phases located in [`src/server/workflows/siteAuditWorkflowPhases.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/siteAuditWorkflowPhases.ts). To adjust crawling speed, you must modify the source code and redeploy the server.

### What happens if I set `maxPages` higher than my plan allows?

The `AuditService.startAudit` function automatically clamps the supplied value against the `AUDIT_LIMITS` constant associated with your billing tier. For example, free plans are capped at 50 pages regardless of the `maxPages` value passed.

### Does `lighthouseStrategy: "none"` improve audit speed?

Yes. Skipping Lighthouse checks eliminates the browser launch, page load, and performance calculation overhead for each URL. When set to `"none"`, the workflow phases bypass the Lighthouse runner entirely, reducing total audit duration significantly.

### Where is the audit configuration stored after creation?

The configuration is serialized as JSON and stored in the audit database record created by `AuditService.startAudit` (lines 46‑69). Subsequent workflow phases and the `getResults` method retrieve and parse this data using `parseAuditConfig` to determine runtime behavior.