# Priority

Priority allows you to dynamically execute some runs ahead or behind others based on any data. This allows you to prioritize some jobs ahead of others without the need for a separate queue. Some use cases for priority include:

- Giving higher priority based on a user's subscription level, for example, free vs. paid users.
- Ensuring that critical work is executed before other work in the queue.
- Prioritizing certain jobs during onboarding to give the user a better first-run experience.

## How to configure priority

```ts
export default inngest.createFunction(
  {
    id: "ai-generate-summary",
    priority: {
      // For enterprise accounts, a given function run will be prioritized
      // ahead of functions that were enqueued up to 120 seconds ago.
      // For all other accounts, the function will run with no priority.
      run: "event.data.account_type == 'enterprise' ? 120 : 0",
    },
    triggers: { event: "ai/summary.requested" },
  },
  async ({ event, step }) => {
    // This function will be prioritized based on the account type
  }
);
```

```go {{ title: "Go" }}
inngestgo.CreateFunction(
	client,
	inngestgo.FunctionOpts{
		ID: "ai-generate-summary",
		Priority: &inngest.ConfigPriority{
			Run: inngestgo.StrPtr("event.data.account_type == 'enterprise' ? 120 : 0"),
		},
	},
	inngestgo.EventTrigger("ai/summary.requested", nil),
	func(ctx context.Context, input inngestgo.Input[map[string]any]) (any, error) {
		// This function will be prioritized based on the account type
		return nil, nil
	},
)
```

```py {{ title: "Python" }}
@inngest.create_function(
  id="ai-generate-summary",
  priority=inngest.Priority(
    run="event.data.account_type == 'enterprise' ? 120 : 0",
  ),
  trigger=inngest.Trigger(event="ai/summary.requested")
)
async def ai_generate_summary(ctx: inngest.Context):
    # This function will be prioritized based on the account type
```

### Configuration reference

- `run` - A dynamic factor [expression](/docs-markdown/guides/writing-expressions), that evaluates to seconds, to prioritize the function by. Returning a positive number will increase that priority ahead of other jobs already in the queue. Returning a negative number will delay the function run's jobs by the given value in seconds.

## How priority works

Functions are scheduled in a priority queue based on the time they should run. By default, all functions are enqueued at the current time (a factor of `0`). If a function has `priority` configured, Inngest evaluates the `run` expression for each new function run based on the input event's data. The `run` expression should return a factor, in seconds, (positive or negative) to adjust the priority of the function run.

Expressions that return a **positive** number will **increase the priority** of the function run ahead of other jobs already in the queue by the given value in seconds. The function will be run ahead of other jobs that were enqueued up to that many seconds ago. For example, if a function run is scheduled with a factor of `120`, it will run ahead of any jobs enqueued in the last 120 seconds, given that they are still in the queue and have not completed.

Expressions that return a **negative** number will **delay** the function run by the given value in seconds.

### Practical example

Given we have three jobs in the queue, each which was enqueued at the following times:

```plaintext
Jobs:          [A,        B,        C       ]
Priority/Time: [12:00:10, 12:00:40, 12:02:10]
```

If the current time is `12:02:30`, and two new jobs are enqueued with the following `run` factors:

```plaintext
- Job X: factor 0
- Job Y: factor 120
```

Then Job Y will run ahead of Job X. Job Y will also run before any jobs scheduled 120 seconds beforehand. The queue will look like this:

```plaintext
Jobs:          [A,        Y,        B,        C,        X     ]
Priority/Time: [12:00:10, 12:00:30, 12:00:40, 12:02:10, 12:02:30]
                          │                             │
                          └ 12:02:30 - 120s = 12:00:30  └ 12:02:30 - 0s = 12:02:30
```

Job Y was successfully prioritized by a factor of `120` seconds ahead of other jobs in the queue.

## Combining with concurrency

Prioritization is most useful when combined with a flow control option that limits throughput, such as [concurrency](/docs-markdown/guides/concurrency). Jobs often wait in the queue when limiting throughput, so prioritization allows you to control the order in which jobs are executed in that backlog.

## Limitations

- The highest priority is `600` (seconds).
- The lowest priority is `-600` (seconds).
- Not compatible with [batching](/docs-markdown/guides/batching).

## Further reference

- [TypeScript SDK Reference](/docs-markdown/reference/functions/run-priority)
- [Python SDK Reference](/docs-markdown/reference/python/functions/create#configuration)