Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Sift Run Service API
version: '1.0'
description: Service to programmatically interact with [runs](/glossary#run).
servers:
- url: https://api.siftstack.com
description: Production
- url: https://gov.api.siftstack.com
description: Gov
security:
- BearerAuth: []
tags:
- name: RunService
description: Service to programmatically interact with [runs](/glossary#run).
externalDocs:
description: Read more about what runs are.
url: https://customer.support.siftstack.com/servicedesk/customer/portal/2/article/265454053
paths:
/api/v2/runs:
get:
summary: ListRuns
description: Retrieve runs using an optional filter.
operationId: RunService_ListRuns
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2ListRunsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: pageSize
description: 'The maximum number of runs to return.
The service may return fewer than this value.
If unspecified, at most 50 runs will be returned.
The maximum value is 1000; values above 1000 will be coerced to 1000.'
in: query
required: false
schema:
type: integer
format: int64
- name: pageToken
description: 'A page token, received from a previous `ListRuns` call.
Provide this to retrieve the subsequent page.
When paginating, all other parameters provided to `ListRuns` must match
the call that provided the page token.'
in: query
required: false
schema:
type: string
- name: filter
description: 'A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string.
Available fields to filter by are `run_id` `organization_id`, `asset_id`, `asset_name`, `client_key`, `name`, `description`, `created_by_user_id`, `modified_by_user_id`,
`created_date`, `modified_date`, `start_time`, `stop_time`, `tag_id`, `asset_tag_id`, `duration`, ''duration_string'', `annotation_comments_count`, `annotation_state`, `archived_date`, `is_archived`,
and `metadata`. Metadata can be used in filters by using `metadata.{metadata_key_name}` as the field name.
`duration` is in the format of elapsed seconds and `duration_string` allows for `h`, `m`, `s`, `ms` suffixes (example: `duration_string > duration(''10h''))
For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions).'
in: query
required: false
schema:
type: string
- name: orderBy
description: 'How to order the retrieved runs. Formatted as a comma-separated string i.e. "FIELD_NAME[ desc],...".
Available fields to order_by are `name`, `description`, `created_date`, `modified_date`, `start_time`, and `stop_time`.
If left empty, items are ordered by `created_date` in descending order (newest-first).
For more information about the format of this field, read [this](https://google.aip.dev/132#ordering)
Example: "created_date desc,modified_date"
Results can also be ordered by the value of a single metadata key, using the same bracket
syntax as `filter`: `metadata["<key name>"][ desc]`. Metadata ordering cannot be combined
with other order_by fields, and runs without the key sort last in both directions. Keys
with relation-typed values cannot be ordered by.
Example: `metadata["test_scenario"] desc`'
in: query
required: false
schema:
type: string
tags:
- RunService
post:
summary: CreateRun
description: Create a run.
operationId: RunService_CreateRun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2CreateRunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v2CreateRunRequest'
description: The request of a call to `RunService_CreateRuns` to create a new run.
required: true
tags:
- RunService
patch:
summary: UpdateRun
description: Updates an existing run using using the list of fields specified in `update_mask`.
operationId: RunService_UpdateRun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2UpdateRunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v2UpdateRunRequest'
description: The request for a call to `RunService_UpdateRun` to update an existing run.
required: true
tags:
- RunService
/api/v2/runs/{runId}:
get:
summary: GetRun
description: Retrieve a run.
operationId: RunService_GetRun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2GetRunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: runId
description: The ID of the run to retrieve.
in: path
required: true
schema:
type: string
tags:
- RunService
delete:
summary: DeleteRun
description: 'Permanently delete a given run. Deprecated: Use update with is_archived.'
operationId: RunService_DeleteRun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2DeleteRunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: runId
in: path
required: true
schema:
type: string
tags:
- RunService
/api/v2/runs/{runId}:create-automatic-run-association-for-assets:
post:
summary: CreateAutomaticRunAssociationForAssets
description: Associates a list of assets with a given run.
operationId: RunService_CreateAutomaticRunAssociationForAssets
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2CreateAutomaticRunAssociationForAssetsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: runId
description: The ID of the run to associate the asset with.
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
assetNames:
type: array
items:
type: string
description: 'A list of asset names to automatically associate with the run.
Any data that is received for these assets will automatically added to the run.
This applies even if the run has concluded, so long as the new data contains
timestamps that are between the `start_time` and `stop_time`.
If any of the assets are already associated with a different run whose run
period (the period between `start_time` and `end_time`) overlaps with the
requested run period, an error will be returned.'
required:
- assetNames
required: true
tags:
- RunService
/api/v2/runs:adhoc:
post:
summary: CreateAdhocRun
description: Create an adhoc run.
operationId: RunService_CreateAdhocRun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2CreateAdhocRunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v2CreateAdhocRunRequest'
description: The request for a call to `RunService_CreateAdhocRun` to create an adhoc run.
required: true
tags:
- RunService
/api/v2/runs:stop:
patch:
summary: StopRun
description: Set the stop time of a run to the current time. To set the stop time of a run to an arbitrary time see `UpdateRun`.
operationId: RunService_StopRun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2StopRunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v2StopRunRequest'
description: The request for a call to `RunService_StopRun` to stop a run.
required: true
tags:
- RunService
/api/v2/runs:validateFilter:
post:
summary: ValidateRunFilter
description: Validates a CEL filter expression against the available run filter fields.
operationId: RunService_ValidateRunFilter
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v2ValidateRunFilterResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v2ValidateRunFilterRequest'
description: The request for a call to `RunService_ValidateRunFilter`.
required: true
tags:
- RunService
components:
schemas:
protobufAny:
type: object
properties:
'@type':
type: string
description: "A URL/resource name that uniquely identifies the type of the serialized\nprotocol buffer message. This string must contain at least\none \"/\" character. The last segment of the URL's path must represent\nthe fully qualified name of the type (as in\n`path/google.protobuf.Duration`). The name should be in a canonical form\n(e.g., leading \".\" is not accepted).\n\nIn practice, teams usually precompile into the binary all types that they\nexpect it to use in the context of Any. However, for URLs which use the\nscheme `http`, `https`, or no scheme, one can optionally set up a type\nserver that maps type URLs to message definitions as follows:\n\n* If no scheme is provided, `https` is assumed.\n* An HTTP GET on the URL must yield a [google.protobuf.Type][]\n value in binary format, or produce an error.\n* Applications are allowed to cache lookup results based on the\n URL, or have them precompiled into a binary to avoid any\n lookup. Therefore, binary compatibility needs to be preserved\n on changes to types. (Use versioned type names to manage\n breaking changes.)\n\nNote: this functionality is not currently available in the official\nprotobuf release, and it is not used for type URLs beginning with\ntype.googleapis.com. As of May 2023, there are no widely used type server\nimplementations and no plans to implement one.\n\nSchemes other than `http`, `https` (or the empty scheme) might be\nused with implementation specific semantics."
additionalProperties: {}
description: "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nProtobuf library provides support to pack/unpack Any values in the form\nof utility functions or additional generated methods of the Any type.\n\nExample 1: Pack and unpack a message in C++.\n\n Foo foo = ...;\n Any any;\n any.PackFrom(foo);\n ...\n if (any.UnpackTo(&foo)) {\n ...\n }\n\nExample 2: Pack and unpack a message in Java.\n\n Foo foo = ...;\n Any any = Any.pack(foo);\n ...\n if (any.is(Foo.class)) {\n foo = any.unpack(Foo.class);\n }\n // or ...\n if (any.isSameTypeAs(Foo.getDefaultInstance())) {\n foo = any.unpack(Foo.getDefaultInstance());\n }\n\n Example 3: Pack and unpack a message in Python.\n\n foo = Foo(...)\n any = Any()\n any.Pack(foo)\n ...\n if any.Is(Foo.DESCRIPTOR):\n any.Unpack(foo)\n ...\n\n Example 4: Pack and unpack a message in Go\n\n foo := &pb.Foo{...}\n any, err := anypb.New(foo)\n if err != nil {\n ...\n }\n ...\n foo := &pb.Foo{}\n if err := any.UnmarshalTo(foo); err != nil {\n ...\n }\n\nThe pack methods provided by protobuf library will by default use\n'type.googleapis.com/full.type.name' as the type URL and the unpack\nmethods only use the fully qualified type name after the last '/'\nin the type URL, for example \"foo.bar.com/x/y.z\" will yield type\nname \"y.z\".\n\nJSON\n====\nThe JSON representation of an `Any` value uses the regular\nrepresentation of the deserialized, embedded message, with an\nadditional field `@type` which contains the type URL. Example:\n\n package google.profile;\n message Person {\n string first_name = 1;\n string last_name = 2;\n }\n\n {\n \"@type\": \"type.googleapis.com/google.profile.Person\",\n \"firstName\": <string>,\n \"lastName\": <string>\n }\n\nIf the embedded message type is well-known and has a custom JSON\nrepresentation, that representation will be embedded adding a field\n`value` which holds the custom JSON in addition to the `@type`\nfield. Example (for message [google.protobuf.Duration][]):\n\n {\n \"@type\": \"type.googleapis.com/google.protobuf.Duration\",\n \"value\": \"1.212s\"\n }"
v2DeleteRunResponse:
type: object
description: The response of a call to `RunService_DeleteRun`.
v2CreateRunResponse:
type: object
properties:
run:
$ref: '#/components/schemas/runsv2Run'
required:
- run
v2GetRunResponse:
type: object
properties:
run:
$ref: '#/components/schemas/runsv2Run'
description: The response of a call to `RunService_GetRun` containing the requested run.
required:
- run
v2StopRunResponse:
type: object
description: The response of a call to `RunService_StopRun` to stop a run.
v2ValidateRunFilterResponse:
type: object
properties:
errorMessage:
type: string
description: Empty string if the filter is valid; otherwise contains the validation error message.
description: The response of a call to `RunService_ValidateRunFilter`.
required:
- errorMessage
v2StopRunRequest:
type: object
properties:
runId:
type: string
description: The request for a call to `RunService_StopRun` to stop a run.
required:
- runId
v2UpdateRunRequest:
type: object
properties:
run:
$ref: '#/components/schemas/runsv2Run'
updateMask:
type: string
description: 'The list of fields to be updated. The fields available to be updated are `name`, `description`,
`start_time`, `stop_time`, `is_pinned`, `client_key`, `tags`,`is_archived`, and `metadata`.
Important Note: When updating the `start_time`, please be aware that if a subsequent data ingestion
commences for this run, the `start_time` will be automatically overwritten and set to the timestamp
corresponding to the beginning of the latest run. Additionally, `client_key` can only be set once either in run creation or in update.
Any subsequent attempt to update `client_key` will result in an error.'
description: The request for a call to `RunService_UpdateRun` to update an existing run.
required:
- run
- updateMask
v2ValidateRunFilterRequest:
type: object
properties:
filter:
type: string
description: The CEL filter expression to validate.
description: The request for a call to `RunService_ValidateRunFilter`.
required:
- filter
v1MetadataValue:
type: object
properties:
key:
$ref: '#/components/schemas/v1MetadataKey'
stringValue:
type: string
numberValue:
type: number
format: double
booleanValue:
type: boolean
relationValue:
$ref: '#/components/schemas/v1MetadataRelationValue'
archivedDate:
type: string
format: date-time
isArchived:
type: boolean
description: Whether the metadata value is archived. This is inferred from whether archived_date is set.
required:
- key
v2UpdateRunResponse:
type: object
properties:
run:
$ref: '#/components/schemas/runsv2Run'
description: The response of a call to `RunService_UpdateRun` containing the updated run.
required:
- run
runsv2Run:
type: object
properties:
runId:
type: string
createdDate:
type: string
format: date-time
modifiedDate:
type: string
format: date-time
createdByUserId:
type: string
modifiedByUserId:
type: string
organizationId:
type: string
startTime:
type: string
format: date-time
stopTime:
type: string
format: date-time
isPinned:
type: boolean
name:
type: string
description:
type: string
tags:
type: array
items:
type: string
defaultReportId:
type: string
clientKey:
type: string
metadata:
type: array
items:
$ref: '#/components/schemas/v1MetadataValue'
description: The metadata values associated with this run.
assetIds:
type: array
items:
type: string
archivedDate:
type: string
format: date-time
isAdhoc:
type: boolean
isArchived:
type: boolean
description: Whether the Run is archived. This is inferred from whether archived_date is set.
duration:
type: string
description: 'The duration of the run. Calculated as the difference between stop_time and start_time.
If the run is ongoing (no stop_time), this represents the duration from start_time to current time.'
required:
- runId
- createdDate
- modifiedDate
- createdByUserId
- modifiedByUserId
- organizationId
- isPinned
- name
- description
- tags
- metadata
- assetIds
- isAdhoc
- isArchived
v1MetadataRelationValue:
type: object
properties:
resourceType:
type: string
resourceId:
type: string
required:
- resourceType
- resourceId
v2CreateAutomaticRunAssociationForAssetsResponse:
type: object
v2CreateRunRequest:
type: object
properties:
name:
type: string
description: The name that will be assigned to the new run.
description:
type: string
description: A description about the new run.
tags:
type: array
items:
type: string
description: Tags to associate with the new run.
startTime:
type: string
format: date-time
description: 'The time at which data ingestion begins for this new run. It must be before the `stop_time`, and it must
be provided if a `stop_time` is provided.
Important note: `start_time` will be automatically computed during data ingestion and will be set
based on the timestamp of the data for this run.'
stopTime:
type: string
format: date-time
description: 'The time at which data ingestion for this new run concludes.
Important note: `stop_time` will be automatically computed during data ingestion and will be
set based on the timestamp of the data for this run.'
organizationId:
type: string
description: An organization ID is only required if the user belongs to multiple organizations.
clientKey:
type: string
description: An arbitrary user-chosen key that uniquely identifies this run. Optional, though it is recommended to provide.
metadata:
type: array
items:
$ref: '#/components/schemas/v1MetadataValue'
description: The metadata values associated with this run.
createDefaultReport:
type: boolean
description: 'Whether to create a default report for this run. This facilitates getting the report ID for live rules that will be automatically created for this run which can streamline programatically creating Campaigns.
Defaults to false if not specified (This default can be changed for your organization by Sift. Contact support to change this default behavior.).'
description: The request of a call to `RunService_CreateRuns` to create a new run.
required:
- name
- description
v1MetadataKeyType:
type: string
enum:
- METADATA_KEY_TYPE_UNSPECIFIED
- METADATA_KEY_TYPE_STRING
- METADATA_KEY_TYPE_NUMBER
- METADATA_KEY_TYPE_BOOLEAN
- METADATA_KEY_TYPE_RELATION
default: METADATA_KEY_TYPE_UNSPECIFIED
description: "Metadata key type.\n\n - METADATA_KEY_TYPE_STRING: string\n - METADATA_KEY_TYPE_NUMBER: number\n - METADATA_KEY_TYPE_BOOLEAN: boolean\n - METADATA_KEY_TYPE_RELATION: relation — references another resource by UUID (e.g. folder membership)"
v2CreateAdhocRunRequest:
type: object
properties:
name:
type: string
description: The name that will be assigned to the new run.
description:
type: string
description: A description about the new run.
startTime:
type: string
format: date-time
title: The time at which data ingestion began for this new run. It must be before the `stop_time`
stopTime:
type: string
format: date-time
description: The time at which data ingestion concluded for this new run.
assetIds:
type: array
items:
type: string
description: A list of asset IDs to associate with the new run.
tags:
type: array
items:
type: string
description: Tags to associate with the new run.
metadata:
type: array
items:
$ref: '#/components/schemas/v1MetadataValue'
description: The metadata values associated with this run.
clientKey:
type: string
description: An arbitrary user-chosen key that uniquely identifies this run. Optional, though it is recommended to provide.
description: The request for a call to `RunService_CreateAdhocRun` to create an adhoc run.
required:
- name
- description
- startTime
- stopTime
- assetIds
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
v1MetadataKey:
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/v1MetadataKeyType'
archivedDate:
type: string
format: date-time
isArchived:
type: boolean
description: "Whether the metadata key is archived. This is inferred from whether archived_date is set.\n\nThe filter field type this key maps to, so a client can build a CEL filter\n against it (`metadata[\"<name>\"]`) and resolve its operators and functions\n from FilterGrammarService. Derived from `type`."
required:
- name
- type
v2ListRunsResponse:
type: object
properties:
runs:
type: array
items:
$ref: '#/components/schemas/runsv2Run'
nextPageToken:
type: string
description: The response of a call to `RunService_ListRuns` containing requested runs.
required:
- runs
v2CreateAdhocRunResponse:
type: object
properties:
run:
$ref: '#/components/schemas/runsv2Run'
description: The response of a call to `RunService_CreateAdhocRun` containing the newly created adhoc run.
required:
- run
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT