# Projects

https://api-docs.lumar.io/docs/ai-visibility/ai-visibility-projects

A project is the top-level container for AI Visibility monitoring. Each project has a primary brand, a set of AI providers, and a schedule that controls automatic prompt execution.

## List projects

Retrieve all AI Visibility projects for an account. Results include metadata like topic and prompt counts, configured AI providers, and the primary brand domain.

```graphql
query GetAiVisibilityProjects($accountId: ObjectID!) {
  getAiVisibilityProjects(
    accountId: $accountId
    first: 10
  ) {
    nodes {
      id
      rawId
      name
      totalTopics
      totalPrompts
      aiProviderTypes
      primaryBrandDomain
      primaryBrandRawId
      scheduleCadence
      nextScheduleRunAt
      autoCrawlEnabled
      freshnessThresholdDays
      createdAt
      updatedAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ"
}
```

You can search projects by name using the `search` parameter:

```graphql
query SearchAiVisibilityProjects($accountId: ObjectID!, $search: String!) {
  getAiVisibilityProjects(
    accountId: $accountId
    first: 10
    search: $search
  ) {
    nodes {
      id
      name
      primaryBrandDomain
    }
    totalCount
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "search": "my brand"
}
```

### Sorting

Projects can be sorted by: `name`, `primaryBrandDomain`, `totalTopics`, `totalPrompts`.

## Get a single project

Fetch a specific project by its ID:

```graphql
query GetAiVisibilityProject(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
) {
  getAiVisibilityProject(
    accountId: $accountId
    aiVisibilityProjectId: $aiVisibilityProjectId
  ) {
    id
    rawId
    name
    scheduleCadence
    nextScheduleRunAt
    autoCrawlEnabled
    freshnessThresholdDays
    primaryBrand {
      id
      rawId
      name
    }
    aiProviders {
      id
      name
      type
    }
    createdAt
    updatedAt
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE"
}
```

## Create a project

Creating a project requires a name, brand name, and brand domain. The primary brand is automatically created as an `own` type brand.

```graphql
mutation CreateAiVisibilityProject(
  $accountId: ObjectID!
  $name: String!
  $brandName: String!
  $brandDomain: String!
  $scheduleCadence: AiVisibilityScheduleCadence
) {
  createAiVisibilityProject(
    input: {
      accountId: $accountId
      name: $name
      brandName: $brandName
      brandDomain: $brandDomain
      scheduleCadence: $scheduleCadence
    }
  ) {
    aiVisibilityProject {
      id
      rawId
      name
      scheduleCadence
      nextScheduleRunAt
      createdAt
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "name": "My Brand Monitoring",
  "brandName": "Lumar",
  "brandDomain": "lumar.io",
  "scheduleCadence": "Daily"
}
```

### Schedule cadence

The `scheduleCadence` field controls how often prompts are automatically sent to AI providers:

| Value             | Description         |
| ----------------- | ------------------- |
| `daily`           | Every day (default) |
| `weekly`          | Once per week       |
| `every_two_weeks` | Every two weeks     |
| `monthly`         | Once per month      |

The schedule cadence also affects the maximum number of prompts allowed in a project. More frequent cadences allow fewer prompts per project.

### AI providers

By default, all AI providers included in your subscription are linked to the project. You can optionally specify `aiVisibilityAiProviderIds` to select a subset of providers.

## Update a project

Update a project's name, schedule cadence, or content evaluation settings:

```graphql
mutation UpdateAiVisibilityProject(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
  $name: String
  $scheduleCadence: AiVisibilityScheduleCadence
  $autoCrawlEnabled: Boolean
  $freshnessThresholdDays: Int
) {
  updateAiVisibilityProject(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
      name: $name
      scheduleCadence: $scheduleCadence
      autoCrawlEnabled: $autoCrawlEnabled
      freshnessThresholdDays: $freshnessThresholdDays
    }
  ) {
    aiVisibilityProject {
      id
      name
      scheduleCadence
      autoCrawlEnabled
      freshnessThresholdDays
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE",
  "name": "Updated Project Name",
  "scheduleCadence": "Weekly",
  "autoCrawlEnabled": true,
  "freshnessThresholdDays": 14
}
```

### Content evaluation settings

- `autoCrawlEnabled` -- When `true`, cited pages from your brand's domains are automatically crawled and evaluated after each prompt run
- `freshnessThresholdDays` -- Number of days (1-90, default 7) before a previously crawled URL is considered stale and re-crawled

:::caution
Changing `scheduleCadence` may reduce the allowed prompt count. If the current prompt count exceeds the new limit, the update will fail with `AI_VISIBILITY_PROMPTS_LIMIT_REACHED`.
:::

## Delete a project

Soft-deletes a project. This is a destructive operation.

```graphql
mutation DeleteAiVisibilityProject(
  $accountId: ObjectID!
  $aiVisibilityProjectId: ObjectID!
) {
  deleteAiVisibilityProject(
    input: {
      accountId: $accountId
      aiVisibilityProjectId: $aiVisibilityProjectId
    }
  ) {
    aiVisibilityProject {
      id
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQxMjM0NQ",
  "aiVisibilityProjectId": "QWlWaXNpYmlsaXR5UHJvamVjdDE"
}
```

## Schema reference

- [`AiVisibilityProject`](/docs/schema/objects/ai-visibility-project.md) -- Project type
- [`CreateAiVisibilityProjectInput`](/docs/schema/inputs/create-ai-visibility-project-input.md) -- Creation input
- [`UpdateAiVisibilityProjectInput`](/docs/schema/inputs/update-ai-visibility-project-input.md) -- Update input
- [`AiVisibilityScheduleCadence`](/docs/schema/enums/ai-visibility-schedule-cadence.md) -- Schedule options