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

# flagReturns

> Flag returns for attention. Starts a run and returns it at once; the returns are worked through in the background. Returns null, and starts nothing, if any id is not a return owned by the caller.

**Required scopes:** [`returns_write`](/docs/api-reference/v3/reference/scopes#scope-returns_write)

## Arguments

**idempotencyKey** `String`

A key of your choosing. Repeating a call with the same key and the same arguments returns the first run rather than starting another.

**returnIds** `[ID!]!` *required*

The ids of the returns to act on (1–500). Returns the action does not apply to are reported as skipped, not as an error.

## Returns

**flagReturns**

One run of a return action over a set of returns. A run works through its returns in the background; poll `returnActionRun` until `status` is no longer `RUNNING`.

**fields**

**action**

The action the run applies. Null for the moment before a run that has only just started reports it.

**counts** *required*

Outcome totals so far.

**fields**

**alreadyRunning** `Int!` *required*

Returns the same action was already in progress on, which the run left alone.

**failed** `Int!` *required*

Returns the action failed on.

**ok** `Int!` *required*

Returns the action was applied to.

**skipped** `Int!` *required*

Returns the action did not apply to.

**total** `Int!` *required*

The returns in the run.

**id** `ID!` *required*

The run's id, for `returnActionRun`.

**results** *required*

One entry per return, in the order they were given. Live while the run is `RUNNING`.

**fields**

**code** `String`

A stable code for a skipped or failed return, such as `INELIGIBLE` or `CLAIM_UNDER_REDO_REVIEW`.

**message** `String`

Why the return was skipped or failed.

**returnId** `ID!` *required*

The id of the return. Read the return itself with the `return` query.

**status** *required*

What the run did to this return.

**status** *required*

Whether the run is still working.

## Example

```graphql theme={null}
mutation {
  flagReturns(idempotencyKey: "...", returnIds: "...") {
    action
    id
    status
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.