Update a scope

patchhttps://api.faraday.ai/v1/scopes/{scope_id}

Update the configuration of a scope.

Authentication

Bearer Authentication

Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.

Authorization: Bearer YOUR_TOKEN

path parameters

scope_idstring<uuid>required

The UUID of a scope

Responses

200Information about the scope

archived_atstring<date-time>

If not null, this resource will no longer receive updates, but will still be visable.

columnsobject

Metadata about the columns in this scope. Useful for advanced target configuration.

Properties of object

columns_for_modeobjectrequired

Available columns for different modes of target export.

Properties of object

aggregatedarray[object]

Available columns for a given mode of target export.

Items of array[object]

aggregationstring

The method of aggregation. Applies to aggregation targets only.

Allowed values: avg, count, countif, mode, ignore

aggregation_criteriastring

For scope columns that can be aggregated with countif (currently just persona sets), this is the value being counted (i.e. the persona ID). Applies to aggregation targets only.

is_identity_colboolean

Set this to true when exporting first party identifiers (given by identity_sets).

If true, scope_col represents the dataset field name being selected (ex: "client_email").

output_colstringrequired

The name of this column in the target export. Can be the same as scope_col.

Match pattern: ^[_a-z][_a-z0-9]*$

scope_colstringrequired

The name of the scope column to export.

Users can supply either the machine-readable name (with underscored uuid) or the human-readable name (with literates).

Match pattern: ^[_a-z][_a-z0-9]*$

hashedarray[object]

Available columns for a given mode of target export.

Items of array[object]

aggregationstring

The method of aggregation. Applies to aggregation targets only.

Allowed values: avg, count, countif, mode, ignore

aggregation_criteriastring

For scope columns that can be aggregated with countif (currently just persona sets), this is the value being counted (i.e. the persona ID). Applies to aggregation targets only.

is_identity_colboolean

Set this to true when exporting first party identifiers (given by identity_sets).

If true, scope_col represents the dataset field name being selected (ex: "client_email").

output_colstringrequired

The name of this column in the target export. Can be the same as scope_col.

Match pattern: ^[_a-z][_a-z0-9]*$

scope_colstringrequired

The name of the scope column to export.

Users can supply either the machine-readable name (with underscored uuid) or the human-readable name (with literates).

Match pattern: ^[_a-z][_a-z0-9]*$

identifiedarray[object]

Available columns for a given mode of target export.

Items of array[object]

aggregationstring

The method of aggregation. Applies to aggregation targets only.

Allowed values: avg, count, countif, mode, ignore

aggregation_criteriastring

For scope columns that can be aggregated with countif (currently just persona sets), this is the value being counted (i.e. the persona ID). Applies to aggregation targets only.

is_identity_colboolean

Set this to true when exporting first party identifiers (given by identity_sets).

If true, scope_col represents the dataset field name being selected (ex: "client_email").

output_colstringrequired

The name of this column in the target export. Can be the same as scope_col.

Match pattern: ^[_a-z][_a-z0-9]*$

scope_colstringrequired

The name of the scope column to export.

Users can supply either the machine-readable name (with underscored uuid) or the human-readable name (with literates).

Match pattern: ^[_a-z][_a-z0-9]*$

referencedarray[object]

Available columns for a given mode of target export.

Items of array[object]

aggregationstring

The method of aggregation. Applies to aggregation targets only.

Allowed values: avg, count, countif, mode, ignore

aggregation_criteriastring

For scope columns that can be aggregated with countif (currently just persona sets), this is the value being counted (i.e. the persona ID). Applies to aggregation targets only.

is_identity_colboolean

Set this to true when exporting first party identifiers (given by identity_sets).

If true, scope_col represents the dataset field name being selected (ex: "client_email").

output_colstringrequired

The name of this column in the target export. Can be the same as scope_col.

Match pattern: ^[_a-z][_a-z0-9]*$

scope_colstringrequired

The name of the scope column to export.

Users can supply either the machine-readable name (with underscored uuid) or the human-readable name (with literates).

Match pattern: ^[_a-z][_a-z0-9]*$

identity_columnsarray[string]required

First party identifiers from all dataset identity_sets populating this scope.

payload_columnsarray[object]required

Payload columns. The shape is a 1:1 mapping of machine-readable payload column names to human-readable column names.

Items of array[object]

human_namestringrequired

Human-readable column name

namestringrequired

Machine-readable column name

created_atstring<date-time>required

When this resource was created.

idstring<uuid>required

A unique ID for this resource.

Example: "8e63467d-9478-4fba-b05a-d5e98fd06d12"

last_read_input_atstring<date-time>

The last time this resource's input was read.

last_updated_config_atstring<date-time>

The last time this resource's configuration was updated. If this is more recent than last_updated_output_at, the resource will be rebuilt.

last_updated_output_atstring<date-time>

The last time this resource successfully built.

namestringrequired

Human-readable label for this scope. Each scope must have a unique name.

Match pattern: ^(?!\s*$).+

payloadobjectrequired

The data to include for each person in this scope.

Properties of object

attributesarray[string]

Include additional traits.

For traits created through output_to_traits via /datasets, specify the trait name.

For traits from Faraday's Internal Graph (FIG), specify the name prefixed by fig/ ex. fig/age.

cohort_idsarray[string]

Specify a list of cohort membership(s) to include. The list can include any cohort, not just those in population.cohort_ids.

explainabilityboolean

Opt-in to include prediction explainability.

outcome_idsarray[string]

Include the propensity score(s) from the specified outcome(s).

persona_set_idsarray[string]

Include the persona assignment(s) from the specified persona set(s).

recommender_idsarray[string]

Include the recommendation(s) from the specified recommender(s).

This feature is experimental and subject to change. To enable this feature, contact your account manager.

populationobjectrequired

The people to include in a scope. Leave cohort_ids empty to include the entire US population.

Properties of object

cohort_idsarray[string]required

Include people from the specified cohorts in this scope.

exclusion_cohort_idsarray[string]

Exclude people from the specified cohorts in this scope.

population_countinteger

Count of the population. If a person appears in multiple cohorts, they are only counted once.

population_residence_countinteger

Residence count of the population. If a residence appears in multiple cohorts, it is only counted once.

previewbooleanrequired

A preview scope provides only a limited number of output records, but
it is not billed.

Example: true

resource_typestringrequired

The type of this resource.

Example: "scopes"

statusstringrequired

The current state of this resource and any updates.

Example: "pending"

Allowed values: new, starting, running, ready, error

status_changed_atstring<date-time>

When the status of this resource was last updated.

status_errorstring

If this resource has status == "error", this will contain an error message.

updated_atstring<date-time>required

When this resource was last updated.

400The request was invalid.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

401No API key was supplied.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

403Access to this resource was forbidden.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

404The requested resource ID was not found.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

500An internal server error occurred.

errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

BAD_REQUEST: The request could not be validated.
FORBIDDEN: You do not have permission to access the specified resour...

Example: "ERROR_TYPE"

Allowed values:

BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT

idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"

notestringrequired

A human-readable description of the error.

Example: "An error occurred"

validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]

contextobjectrequired

More information about the error.

Properties of object

errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

Tags

scopes

Test request

Request snippet

curl -X PATCH 'https://api.faraday.ai/v1/scopes/{scope_id}' \
  -H 'Content-Type: application/json+merge-patch' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
      "name": "string (pattern: ^(?!\\s*$).+)",
      "payload": {
        "attributes": [
          "fig/age"
        ],
        "cohort_ids": [
          "5bf9aa70-7bf1-4ef1-a131-8c84441be231"
        ],
        "explainability": true,
        "outcome_ids": [
          "b80217ae-7628-4c66-8a19-5bf452495c39"
        ],
        "persona_set_ids": [
          "4b3f42dd-b6c3-4f0f-ac18-9e6e47321f83"
        ],
        "recommender_ids": [
          "b4f9c92c-b0e5-4626-9674-e8f88e5adb62"
        ]
      },
      "population": {
        "cohort_ids": [
          "5bf9aa70-7bf1-4ef1-a131-8c84441be231"
        ],
        "exclusion_cohort_ids": [
          "54270059-c9b5-42c6-a728-36b69a1cf3d8"
        ]
      },
      "preview": true
    }'

Example response

application/json

{
  "archived_at": "2024-01-01T12:00:00Z",
  "columns": {
    "columns_for_mode": {
      "aggregated": [
        {
          "aggregation": "avg",
          "aggregation_criteria": "string",
          "is_identity_col": true,
          "output_col": "string (pattern: ^[_a-z][_a-z0-9]*$)",
          "scope_col": "string (pattern: ^[_a-z][_a-z0-9]*$)"
        }
      ],
      "hashed": [
        {
          "aggregation": "avg",
          "aggregation_criteria": "string",
          "is_identity_col": true,
          "output_col": "string (pattern: ^[_a-z][_a-z0-9]*$)",
          "scope_col": "string (pattern: ^[_a-z][_a-z0-9]*$)"
        }
      ],
      "identified": [
        {
          "aggregation": "avg",
          "aggregation_criteria": "string",
          "is_identity_col": true,
          "output_col": "string (pattern: ^[_a-z][_a-z0-9]*$)",
          "scope_col": "string (pattern: ^[_a-z][_a-z0-9]*$)"
        }
      ],
      "referenced": [
        {
          "aggregation": "avg",
          "aggregation_criteria": "string",
          "is_identity_col": true,
          "output_col": "string (pattern: ^[_a-z][_a-z0-9]*$)",
          "scope_col": "string (pattern: ^[_a-z][_a-z0-9]*$)"
        }
      ]
    },
    "identity_columns": [
      "string"
    ],
    "payload_columns": [
      {
        "human_name": "string",
        "name": "string"
      }
    ]
  },
  "created_at": "2024-01-01T12:00:00Z",
  "id": "8e63467d-9478-4fba-b05a-d5e98fd06d12",
  "last_read_input_at": "2024-01-01T12:00:00Z",
  "last_updated_config_at": "2024-01-01T12:00:00Z",
  "last_updated_output_at": "2024-01-01T12:00:00Z",
  "name": "string (pattern: ^(?!\\s*$).+)",
  "payload": {
    "attributes": [
      "fig/age"
    ],
    "cohort_ids": [
      "5bf9aa70-7bf1-4ef1-a131-8c84441be231"
    ],
    "explainability": true,
    "outcome_ids": [
      "b80217ae-7628-4c66-8a19-5bf452495c39"
    ],
    "persona_set_ids": [
      "4b3f42dd-b6c3-4f0f-ac18-9e6e47321f83"
    ],
    "recommender_ids": [
      "b4f9c92c-b0e5-4626-9674-e8f88e5adb62"
    ]
  },
  "population": {
    "cohort_ids": [
      "5bf9aa70-7bf1-4ef1-a131-8c84441be231"
    ],
    "exclusion_cohort_ids": [
      "54270059-c9b5-42c6-a728-36b69a1cf3d8"
    ]
  },
  "population_count": 0,
  "population_residence_count": 0,
  "preview": true,
  "resource_type": "scopes",
  "status": "pending",
  "status_changed_at": "2024-01-01T12:00:00Z",
  "status_error": "string",
  "updated_at": "2024-01-01T12:00:00Z"
}